API¶
nanodbc is a library offering the primary API in C++ language.
All functions and classes provided by the nanodbc library reside
in namespace nanodbc
, all macros have prefix NANODBC_
.
The entirety of nanodbc can be found within this file and nanodbc.cpp.
-
namespace
nanodbc
¶ The entirety of nanodbc can be found within this one namespace.
- Note
This library does not make any exception safety guarantees, but should work just fine with a threading enabled ODBC driver. If you want to use nanodbc objects in threads I recommend each thread keep their own connection to the database. Otherwise you must synchronize any access to nanodbc objects.
Typedefs
-
typedef std::string
string
¶
-
typedef std::u16string
wide_string
¶
-
typedef wide_string::value_type
wide_char_t
¶
-
typedef long
null_type
¶
-
template<typename
T
>
usingis_string
= std::integral_constant<bool, std::is_same<typename std::decay<T>::type, std::string>::value || std::is_same<typename std::decay<T>::type, wide_string>::value>¶ A type trait for testing if a type is a std::basic_string compatible with the current nanodbc configuration.
-
template<typename
T
>
usingis_character
= std::integral_constant<bool, std::is_same<typename std::decay<T>::type, std::string::value_type>::value || std::is_same<typename std::decay<T>::type, wide_char_t>::value>¶ A type trait for testing if a type is a character compatible with the current nanodbc configuration.
-
template<typename
T
>
usingenable_if_character
= typename std::enable_if<is_character<T>::value>::type¶
Functions
-
result_iterator
begin
(result &r)¶ Returns an iterator to the beginning of the given result set.
-
result_iterator
end
(result&)¶ Returns an iterator to the end of a result set.
The default-constructed
nanodbc::result_iterator
is known as the end-of-result iterator. When a validnanodbc::result_iterator
reaches the end of the underlying result set, it becomes equal to the end-of-result iterator. Dereferencing or incrementing it further is undefined.
-
std::list<datasource>
list_datasources
()¶ Returns a list of ODBC data sources on your system.
-
result
execute
(connection &conn, const string &query, long batch_operations = 1, long timeout = 0)¶ Immediately opens, prepares, and executes the given query directly on the given connection.
- Return
A result set object.
- Attention
You will want to use transactions if you are doing batch operations because it will prevent auto commits from occurring after each individual operation is executed.
- See
open(), prepare(), execute(), result, transaction
- 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 is 0 indicating no timeout.
-
void
just_execute
(connection &conn, const string &query, long batch_operations = 1, long timeout = 0)¶ Opens, prepares, and executes query directly without creating result object.
- Return
A result set object.
- Attention
You will want to use transactions if you are doing batch operations because it will prevent auto commits from occurring after each individual operation is executed.
- See
open(), prepare(), execute(), result, transaction
- 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
: The number in seconds before query timeout. Default is 0 indicating no timeout.
-
result
execute
(statement &stmt, long batch_operations = 1)¶ Execute the previously prepared query now.
- Return
A result set object.
- Attention
You will want to use transactions if you are doing batch operations because it will prevent auto commits from occurring after each individual operation is executed.
- See
- Parameters
stmt
: The prepared statement that will be executed.batch_operations
: Rows to fetch per rowset, or the number of batch parameters to process.
- Exceptions
-
void
just_execute
(statement &stmt, long batch_operations = 1)¶ Execute the previously prepared query now and without creating result object.
- Return
A result set object.
- Attention
You will want to use transactions if you are doing batch operations because it will prevent auto commits from occurring after each individual operation is executed.
- See
- Parameters
stmt
: The prepared statement that will be executed.batch_operations
: Rows to fetch per rowset, or the number of batch parameters to process.
- Exceptions
-
result
transact
(statement &stmt, long batch_operations)¶ Execute the previously prepared query now.
Executes within the context of a transaction object, commits directly after execution.
- Return
A result set object.
- See
open(), prepare(), execute(), result, transaction
- Parameters
stmt
: The prepared statement that will be executed in batch.batch_operations
: Rows to fetch per rowset, or the number of batch parameters to process.
- Exceptions
-
void
just_transact
(statement &stmt, long batch_operations)¶ Execute the previously prepared query now and without creating result object.
Executes within the context of a transaction object, commits directly after execution.
- Return
A result set object.
- See
open(), prepare(), execute(), result, transaction
- Parameters
stmt
: The prepared statement that will be executed in batch.batch_operations
: Rows to fetch per rowset, or the number of batch parameters to process.
- Exceptions
-
void
prepare
(statement &stmt, const string &query, long timeout = 0)¶ Prepares the given statement to execute on it associated connection.
If the statement is not open throws programming_error.
- See
open()
- Parameters
stmt
: The prepared statement that will be executed in batch.query
: The SQL query that will be executed.timeout
: The number in seconds before query timeout. Default is 0 indicating no timeout.
- Exceptions
-
class
catalog
¶ - #include <nanodbc.h>
A resource for get catalog information from connected data source.
Queries are performed using the Catalog Functions in ODBC. All provided operations are convenient wrappers around the ODBC API The original ODBC behaviour should not be affected by any added processing.
Public Functions
-
catalog
(connection &conn)¶ Creates catalog operating on database accessible through the specified connection.
-
catalog::tables
find_tables
(const string &table = string(), const string &type = string(), const string &schema = string(), const string &catalog = string())¶ Creates result set with catalogs, schemas, tables, or table types.
Tables information is obtained by executing
SQLTable
function within scope of the connected database accessible with the specified connection. Since this function is implemented in terms of theSQLTable
s, it returns result set ordered by TABLE_TYPE, TABLE_CAT, TABLE_SCHEM, and TABLE_NAME.All arguments are treated as the Pattern Value Arguments. Empty string argument is equivalent to passing the search pattern ‘’.
-
catalog::table_privileges
find_table_privileges
(const string &catalog, const string &table = string(), const string &schema = string())¶ Creates result set with tables and the privileges associated with each table. Tables information is obtained by executing
SQLTablePrivileges
function within scope of the connected database accessible with the specified connection. Since this function is implemented in terms of theSQLTablePrivileges
s, it returns result set ordered by TABLE_CAT, TABLE_SCHEM, TABLE_NAME, PRIVILEGE, and GRANTEE.- Note
Due to the fact catalog cannot is not the Pattern Value Argument, order of parameters is different than in the other catalog look-up functions.
- Parameters
catalog
: The table catalog. It cannot contain a string search pattern.schema
: String search pattern for schema names, treated as the Pattern Value Arguments.table
: String search pattern for table names, treated as the Pattern Value Arguments.
-
catalog::columns
find_columns
(const string &column = string(), const string &table = string(), const string &schema = string(), const string &catalog = string())¶ Creates result set with columns in one or more tables.
Columns information is obtained by executing
SQLColumns
function within scope of the connected database accessible with the specified connection. Since this function is implemented in terms of theSQLColumns
, it returns result set ordered by TABLE_CAT, TABLE_SCHEM, TABLE_NAME, and ORDINAL_POSITION.All arguments are treated as the Pattern Value Arguments. Empty string argument is equivalent to passing the search pattern ‘’.
-
catalog::primary_keys
find_primary_keys
(const string &table, const string &schema = string(), const string &catalog = string())¶ Creates result set with columns that compose the primary key of a single table.
Returns result set with column names that make up the primary key for a table. The primary key information is obtained by executing
SQLPrimaryKey
function within scope of the connected database accessible with the specified connection.All arguments are treated as the Pattern Value Arguments. Empty string argument is equivalent to passing the search pattern ‘’.
Private Members
-
connection
conn_
¶
-
class
columns
¶ - #include <nanodbc.h>
Result set for a list of columns in one or more tables.
Public Functions
-
bool
next
()¶ Move to the next result in the result set.
-
short
data_type
() const¶ Fetch column data type.
-
long
column_size
() const¶ Fetch column size.
-
long
buffer_length
() const¶ Fetch buffer length.
-
short
decimal_digits
() const¶ Fetch decimal digits.
-
short
numeric_precision_radix
() const¶ Fetch numeric precission.
-
short
nullable
() const¶ True iff column is nullable.
-
short
sql_data_type
() const¶ Fetch column’s SQL data type.
-
short
sql_datetime_subtype
() const¶ Fetch datetime subtype of column.
-
long
char_octet_length
() const¶ Fetch char octet length.
-
long
ordinal_position
() const¶ Ordinal position of the column in the table. The first column in the table is number 1. Returns ORDINAL_POSITION column value in result set returned by SQLColumns.
Friends
- friend class nanodbc::catalog
-
bool
-
class
primary_keys
¶ - #include <nanodbc.h>
Result set for a list of columns that compose the primary key of a single table.
Public Functions
-
bool
next
()¶ Move to the next result in the result set.
-
short
column_number
() const¶ Column sequence number in the key (starting with 1). Returns valye of KEY_SEQ column in result set returned by SQLPrimaryKeys.
Friends
- friend class nanodbc::catalog
-
bool
-
class
table_privileges
¶ - #include <nanodbc.h>
Result set for a list of tables and the privileges associated with each table.
Public Functions
-
bool
next
()¶ Move to the next result in the result set.
Friends
- friend class nanodbc::catalog
-
bool
-
-
class
connection
¶ - #include <nanodbc.h>
Manages and encapsulates ODBC resources such as the connection and environment handles.
Public Functions
-
connection
()¶ Create new connection object, initially not connected.
-
connection
(const connection &rhs)¶ Copy constructor.
-
connection
(connection &&rhs) noexcept¶ Move constructor.
-
connection &
operator=
(connection rhs)¶ Assignment.
-
void
swap
(connection&) noexcept¶ Member swap.
-
connection
(const string &dsn, const string &user, const string &pass, long timeout = 0)¶ Create new connection object and immediately connect to the given data source.
The function calls ODBC API SQLConnect.
- See
- Parameters
dsn
: The name of the data source name (DSN).user
: The username for authenticating to the data source.pass
: The password for authenticating to the data source.timeout
: Seconds before connection timeout. Default 0 meaning no timeout.
- Exceptions
-
connection
(const string &connection_string, long timeout = 0)¶ Create new connection object and immediately connect using the given connection string.
The function calls ODBC API SQLDriverConnect.
- See
- Parameters
connection_string
: The connection string for establishing a connection.timeout
: Seconds before connection timeout. Default is 0 indicating no timeout.
- Exceptions
-
~connection
() noexcept¶ Automatically disconnects from the database and frees all associated resources.
Will not throw even if disconnecting causes some kind of error and raises an exception. If you explicitly need to know if disconnect() succeeds, call it directly.
-
void
allocate
()¶ Allocate environment and connection handles.
Allows on-demand allocation of handles to configure the ODBC environment and attributes, before database connection is established. Typically, user does not have to make this call explicitly.
- See
- Exceptions
-
void
deallocate
()¶ Release environment and connection handles.
- See
-
void
connect
(const string &dsn, const string &user, const string &pass, long timeout = 0)¶ Connect to the given data source.
- See
- Parameters
dsn
: The name of the data source.user
: The username for authenticating to the data source.pass
: The password for authenticating to the data source.timeout
: Seconds before connection timeout. Default is 0 indicating no timeout.
- Exceptions
-
void
connect
(const string &connection_string, long timeout = 0)¶ Connect using the given connection string.
- See
- Parameters
connection_string
: The connection string for establishing a connection.timeout
: Seconds before connection timeout. Default is 0 indicating no timeout.
- Exceptions
-
bool
async_connect
(const string &dsn, const string &user, const string &pass, void *event_handle, long timeout = 0)¶ Initiate an asynchronous connection operation to the given data source.
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_DBC_EVENT
andSQLCompleteAsync
are extant. Otherwise this method will be defined, but not implemented.Asynchronous features can be disabled entierly by defining
NANODBC_DISABLE_ASYNC
when building nanodbc.- Return
Boolean: true if event handle needs to be awaited, false if connection is ready now.
- See
- Parameters
dsn
: The name of the data source.user
: The username for authenticating to the data source.pass
: The password for authenticating to the data source.event_handle
: The event handle the caller will wait before calling async_complete.timeout
: Seconds before connection timeout. Default is 0 indicating no timeout.
- Exceptions
-
bool
async_connect
(const string &connection_string, void *event_handle, long timeout = 0)¶ Initiate an asynchronous connection operation using the given connection string.
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_DBC_EVENT
andSQLCompleteAsync
are extant. Otherwise this method will be defined, but not implemented.Asynchronous features can be disabled entierly by defining
NANODBC_DISABLE_ASYNC
when building nanodbc.- Return
Boolean: true if event handle needs to be awaited, false if connection is ready now.
- See
- Parameters
connection_string
: The connection string for establishing a connection.event_handle
: Event handle the caller will wait before calling async_complete.timeout
: Seconds before connection timeout. Default is 0 indicating no timeout.
- Exceptions
-
void
async_complete
()¶ Completes a previously initiated asynchronous connection operation.
Asynchronous features can be disabled entierly by defining
NANODBC_DISABLE_ASYNC
when building nanodbc.
-
bool
connected
() const¶ Returns true if connected to the database.
-
void
disconnect
()¶ Disconnects from the database, but maintains environment and handle resources.
-
std::size_t
transactions
() const¶ Returns the number of transactions currently held for this connection.
-
void *
native_dbc_handle
() const¶ Returns the native ODBC database connection handle.
-
void *
native_env_handle
() const¶ Returns the native ODBC environment handle.
-
template<class
T
>
Tget_info
(short info_type) const¶ Returns information from the ODBC connection as a string or fixed-size value. The general information about the driver and data source associated with a connection is obtained using
SQLGetInfo
function.
-
string
dbms_name
() const¶ Returns name of the DBMS product. Returns the ODBC information type SQL_DBMS_NAME of the DBMS product accesssed by the driver via the current connection.
-
string
dbms_version
() const¶ Returns version of the DBMS product. Returns the ODBC information type SQL_DBMS_VER of the DBMS product accesssed by the driver via the current connection.
Private Functions
-
std::size_t
ref_transaction
()¶
-
std::size_t
unref_transaction
()¶
-
bool
rollback
() const¶
-
void
rollback
(bool onoff)¶
Private Members
-
std::shared_ptr<connection_impl>
impl_
¶
Friends
- friend class nanodbc::transaction::transaction_impl
-
-
class
database_error
: public runtime_error¶ - #include <nanodbc.h>
General database error.
- See
Exception types
Public Functions
-
database_error
(void *handle, short handle_type, const std::string &info = "")¶ Creates runtime_error with message about last ODBC error.
- Parameters
handle
: The native ODBC statement or connection handle.handle_type
: The native ODBC handle type code for the given handle.info
: Additional info that will be appended to the beginning of the error message.
-
const char *
what
() const noexcept¶
-
long
native
() const noexcept¶
-
const std::string
state
() const noexcept¶
-
struct
datasource
¶
-
struct
date
¶ - #include <nanodbc.h>
A type for representing date data.
-
struct
driver
¶ - #include <nanodbc.h>
Information on a configured ODBC driver.
Public Members
-
struct
attribute
¶ - #include <nanodbc.h>
Driver attributes.
-
struct
-
class
index_range_error
: public runtime_error¶ - #include <nanodbc.h>
Index out of range.
- See
Exception types
-
class
null_access_error
: public runtime_error¶ - #include <nanodbc.h>
Accessed null data.
- See
Exception types
-
class
programming_error
: public runtime_error¶ - #include <nanodbc.h>
Programming logic error.
- See
Exception types
-
class
result
¶ - #include <nanodbc.h>
A resource for managing result sets from statement execution.
- See
- Note
result objects may be copied, however all copies will refer to the same result set.
Public Functions
-
result
()¶ Empty result set.
-
~result
() noexcept¶ Free result set.
-
void *
native_statement_handle
() const¶ 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.
- Exceptions
-
bool
has_affected_rows
() const¶ Reports if number of affected rows is available.
- Return
true if number of affected rows is known, regardless of the value; false if the number is not available.
- Exceptions
assert(r.has_affected_rows() == (r.affected_rows() >= 0));
-
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.
- Exceptions
-
bool
first
()¶ Fetches the first row in the current result set.
- Return
true if there are more results or false otherwise.
- Exceptions
-
bool
last
()¶ Fetches the last row in the current result set.
- Return
true if there are more results or false otherwise.
- Exceptions
-
bool
next
()¶ Fetches the next row in the current result set.
- Return
true if there are more results or false otherwise.
- Exceptions
-
bool
async_next
(void *event_handle)¶ Initiates an asynchronous fetch of the next row in the current result set.
- Return
true if the caller needs to wait for the event to be signalled, false if complete_next() can be called immediately.
- Exceptions
-
bool
complete_next
()¶ Completes a previously-initiated async fetch for next row in the current result set.
- Return
true if there are more results or false otherwise.
- Exceptions
-
bool
prior
()¶ Fetches the prior row in the current result set.
- Return
true if there are more results or false otherwise.
- Exceptions
-
bool
move
(long row)¶ Moves to and fetches the specified row in the current result set.
- Return
true if there are results or false otherwise.
- Exceptions
-
bool
skip
(long rows)¶ Skips a number of rows and then fetches the resulting row in the current result set.
- Return
true if there are results or false otherwise.
- Exceptions
-
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.
Wraps unbind(short column)
- Exceptions
-
void
unbind
(const string &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
-
void
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
-
template<class
T
>
voidget_ref
(short column, T &result) const¶ Gets data from the given column of the current rowset.
Columns are numbered from left to right and 0-indexed.
- Parameters
column
: position.result
: The column’s value will be written to this parameter.
- Exceptions
-
template<class
T
>
voidget_ref
(short column, const T &fallback, T &result) const¶ Gets data from the given column of the current rowset.
If the data is null, fallback is returned instead.
Columns are numbered from left to right and 0-indexed.
- Parameters
column
: position.fallback
: if value is null, return fallback instead.result
: The column’s value will be written to this parameter.
- Exceptions
-
template<class
T
>
voidget_ref
(const string &column_name, T &result) const¶ Gets data from the given column by name of the current rowset.
- Parameters
column_name
: column’s name.result
: The column’s value will be written to this parameter.
- Exceptions
-
template<class
T
>
voidget_ref
(const string &column_name, const T &fallback, T &result) const¶ Gets data from the given column by name of the current rowset.
If the data is null, fallback is returned instead.
- Parameters
column_name
: column’s name.fallback
: if value is null, return fallback instead.result
: The column’s value will be written to this parameter.
- Exceptions
-
template<class
T
>
Tget
(short column) const¶ Gets data from the given column of the current rowset.
Columns are numbered from left to right and 0-indexed.
- Parameters
column
: position.
- Exceptions
-
template<class
T
>
Tget
(short column, const T &fallback) const¶ Gets data from the given column of the current rowset.
If the data is null, fallback is returned instead.
Columns are numbered from left to right and 0-indexed.
- Parameters
column
: position.fallback
: if value is null, return fallback instead.
- Exceptions
-
template<class
T
>
Tget
(const string &column_name) const¶ Gets data from the given column by name of the current rowset.
- Parameters
column_name
: column’s name.
- Exceptions
-
template<class
T
>
Tget
(const string &column_name, const T &fallback) const¶ Gets data from the given column by name of the current rowset.
If the data is null, fallback is returned instead.
- Parameters
column_name
: column’s name.fallback
: if value is null, return fallback instead.
- Exceptions
-
bool
is_null
(short column) const¶ Returns true if and only if the given column of the current rowset is null.
There is a bug/limitation in ODBC drivers for SQL Server (and possibly others) which causes SQLBindCol() to never write SQL_NOT_NULL to the length/indicator buffer unless you also bind the data column. nanodbc’s is_null() will return correct values for (n)varchar(max) columns when you ensure that SQLGetData() has been called for that column (i.e. after get() or get_ref() is called).
Columns are numbered from left to right and 0-indexed.
- See
- Parameters
column
: position.
- Exceptions
-
bool
is_null
(const string &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
- Parameters
column_name
: column’s name.
- Exceptions
-
bool
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
-
bool
is_bound
(const string &column_name) const¶ Returns true if we have bound a buffer to the given column.
See is_bound(short column) for details.
- See
- Parameters
column_name
: column’s name.
- Exceptions
-
short
column
(const string &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
-
string
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
-
long
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
-
long
column_size
(const string &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.
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
-
int
column_decimal_digits
(const string &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
(const string &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.
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.
-
string
column_datatype_name
(const string &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.
-
int
column_c_datatype
(short column) const¶ Returns a identifying integer value representing the C type of this column.
-
int
column_c_datatype
(const string &column_name) const¶ Returns a identifying integer value representing the C type of this column by name.
-
bool
next_result
()¶ Returns the next result, e.g. when stored procedure returns multiple result sets.
-
operator bool
() const¶ If and only if result object is valid, returns true.
Private Members
-
std::shared_ptr<result_impl>
impl_
¶
Friends
- friend class nanodbc::statement::statement_impl
- friend class nanodbc::catalog
-
class
result_iterator
¶ - #include <nanodbc.h>
Single pass input iterator that accesses successive rows in the attached result set.
Public Types
-
typedef std::input_iterator_tag
iterator_category
¶ Category of iterator.
-
typedef std::ptrdiff_t
difference_type
¶ Iterator difference.
Public Functions
-
result_iterator
() = default¶ Default iterator; an empty result set.
-
result_iterator &
operator++
()¶ Iteration.
-
result_iterator
operator++
(int)¶ Iteration.
-
bool
operator==
(result_iterator const &rhs) const¶ Iterators are equal if they a tied to the same native statemnt handle, or both empty.
-
bool
operator!=
(result_iterator const &rhs) const¶ Iterators are not equal if they have different native statemnt handles.
-
typedef std::input_iterator_tag
-
class
statement
¶ - #include <nanodbc.h>
Represents a statement on the database.
Public Types
-
enum
param_direction
¶ Provides support for retrieving output/return parameters.
- See
Binding parameters
Values:
-
enumerator
PARAM_IN
¶ Binding an input parameter.
-
enumerator
PARAM_OUT
¶ Binding an output parameter.
-
enumerator
PARAM_INOUT
¶ Binding an input/output parameter.
-
enumerator
PARAM_RETURN
¶ Binding a return parameter.
Public 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, const string &query, long timeout = 0)¶ Constructs and prepares a statement using the given connection and query.
- See
execute(), just_execute(), execute_direct(), just_execute_direct(), open(), prepare()
- Parameters
conn
: The connection to use.query
: The SQL query statement.timeout
: The number in seconds before query timeout. Default: 0 meaning no timeout.
-
void
open
(class connection &conn)¶ Creates a statement for the given connection.
- Parameters
conn
: The connection where the statement will be executed.
- Exceptions
-
bool
open
() const¶ Returns true if connection is open.
-
bool
connected
() const¶ Returns true if connected to the database.
-
class connection &
connection
()¶ Returns the associated connection object if any.
-
const class connection &
connection
() 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.
- Exceptions
-
void
prepare
(class connection &conn, const string &query, long timeout = 0)¶ Opens and prepares the given statement to execute on the given connection.
- See
- 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.
- Exceptions
-
void
prepare
(const string &query, long timeout = 0)¶ Prepares the given statement to execute its associated connection.
- Note
If the statement is not open throws programming_error.
- See
- Parameters
query
: The SQL query that will be executed.timeout
: The number in seconds before query timeout. Default 0 meaning no timeout.
- Exceptions
-
void
timeout
(long timeout = 0)¶ Sets the number in seconds before query timeout. Default is 0 indicating no timeout.
- Exceptions
-
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.
- Return
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
- 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.
-
bool
async_prepare
(const string &query, void *event_handle, long timeout = 0)¶ Prepare the given statement, 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
andSQLCompleteAsync
are extant. Otherwise this method will be defined, but not implemented.- Note
If the statement is not open throws programming_error.
Asynchronous features can be disabled entirely by defining
NANODBC_DISABLE_ASYNC
when building nanodbc.- Return
Boolean: true if the event handle needs to be awaited, false is result is ready now.
- See
- 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
-
void
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
andSQLCompleteAsync
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.- See
- Exceptions
-
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.
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
andSQLCompleteAsync
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.- Return
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
complete_execute(), open(), prepare(), execute(), result, transaction
- 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
-
bool
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
andSQLCompleteAsync
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.- Return
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
- 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
-
class result
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
andSQLCompleteAsync
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.- Return
A result set object.
- See
- Exceptions
- Parameters
batch_operations
: Rows to fetch per rowset or number of batch parameters to process.
-
NANODBC_DEPRECATED class result async_complete (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, const string &query, long batch_operations = 1, long timeout = 0)¶ Execute the previously prepared query now without constructing result object.
- Return
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
open(), prepare(), execute(), execute_direct(), result, transaction
- 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
-
class result
execute
(long batch_operations = 1, long timeout = 0)¶ Execute the previously prepared query now.
- Return
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
- 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
-
void
just_execute
(long batch_operations = 1, long timeout = 0)¶ Execute the previously prepared query now without constructing result object.
- Return
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
- 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
-
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.
- Return
A result set object.
- 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
-
long
affected_rows
() const¶ Returns rows affected by the request or -1 if affected rows is not available.
- Exceptions
-
short
columns
() const¶ Returns the number of columns in a result set.
- Exceptions
-
void
reset_parameters
() noexcept¶ Resets all currently bound parameters.
-
short
parameters
() const¶ Returns the number of parameters in the statement.
- Exceptions
-
unsigned long
parameter_size
(short param_index) const¶ Returns parameter size for indicated parameter placeholder in a prepared statement.
-
template<class
T
>
voidbind
(short param_index, T const *value, param_direction direction = PARAM_IN)¶ Binds given value to given parameter placeholder number in the prepared statement.
If your prepared SQL query has any ? placeholders, this is how you bind values to them. Placeholder numbers count from left to right and are 0-indexed.
It is NOT possible to use these functions for batch operations as number of elements is not specified here.
- Parameters
param_index
: Zero-based index of parameter marker (placeholder position).value
: Value to substitute into placeholder.direction
: ODBC parameter direction.
- Exceptions
-
template<class
T
>
voidbind
(short param_index, T const *values, std::size_t batch_size, param_direction direction = PARAM_IN)¶ Binds multiple values.
- See
Binding multiple non-string values
-
template<class
T
>
voidbind
(short param_index, T const *values, std::size_t batch_size, T const *null_sentry, param_direction direction = PARAM_IN)¶ Binds multiple values.
- See
Binding multiple non-string values
-
template<class
T
>
voidbind
(short param_index, T const *values, std::size_t batch_size, bool const *nulls, param_direction direction = PARAM_IN)¶ Binds multiple values.
- See
Binding multiple non-string values
-
void
bind
(short param_index, std::vector<std::vector<uint8_t>> const &values, param_direction direction = PARAM_IN)¶ Binds multiple values.
- See
Binding multiple non-string 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.
- See
Binding multiple non-string 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.
- See
Binding multiple non-string values
-
template<class
T
, typename = enable_if_character<T>>
voidbind_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.
- See
-
template<class
T
, typename = enable_if_string<T>>
voidbind_strings
(short param_index, std::vector<T> const &values, param_direction direction = PARAM_IN)¶ Binds multiple string values.
Size of the values vector indicates number of values to bind. Longest string in the array determines maximum length of individual value.
- See
-
template<std::size_t
BatchSize
, std::size_tValueSize
, classT
, typename = enable_if_character<T>>
voidbind_strings
(short param_index, T const (&values)[BatchSize][ValueSize], param_direction direction = PARAM_IN)¶ Binds multiple string values.
- See
-
template<class
T
, typename = enable_if_character<T>>
voidbind_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.
- See
-
template<class
T
, typename = enable_if_string<T>>
voidbind_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.
- See
-
template<std::size_t
BatchSize
, std::size_tValueSize
, classT
, typename = enable_if_character<T>>
voidbind_strings
(short param_index, T const (&values)[BatchSize][ValueSize], T const *null_sentry, param_direction direction = PARAM_IN)¶ Binds multiple string values.
- See
-
template<class
T
, typename = enable_if_character<T>>
voidbind_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.
- See
-
template<class
T
, typename = enable_if_string<T>>
voidbind_strings
(short param_index, std::vector<T> const &values, bool const *nulls, param_direction direction = PARAM_IN)¶ Binds multiple string values.
- See
-
template<std::size_t
BatchSize
, std::size_tValueSize
, classT
, typename = enable_if_character<T>>
voidbind_strings
(short param_index, T const (&values)[BatchSize][ValueSize], bool const *nulls, param_direction direction = PARAM_IN)¶ Binds multiple string values.
- See
-
void
bind_null
(short param_index, std::size_t batch_size = 1)¶ Binds null values to the parameter placeholder number in the prepared statement.
If your prepared SQL query has any parameter markers, ? (question mark) placeholders, this is how you bind values to them. Parameter markers are numbered using Zero-based index from left to right.
It is possible to use this function for batch operations.
- Parameters
param_index
: Zero-based index of parameter marker (placeholder position).batch_size
: The number of elements being bound.
- Exceptions
-
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.
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
Private Types
-
typedef std::function<bool(std::size_t)>
null_predicate_type
¶
Private Members
-
std::shared_ptr<statement_impl>
impl_
¶
Friends
- friend class nanodbc::result
-
enum
-
struct
time
¶ - #include <nanodbc.h>
A type for representing time data.
-
struct
timestamp
¶ - #include <nanodbc.h>
A type for representing timestamp data.
Public Members
-
std::int16_t
year
¶ Year [0-inf).
-
std::int16_t
month
¶ Month of the year [1-12].
-
std::int16_t
day
¶ Day of the month [1-31].
-
std::int16_t
hour
¶ Hours since midnight [0-23].
-
std::int16_t
min
¶ Minutes after the hour [0-59].
-
std::int16_t
sec
¶ Seconds after the minute.
-
std::int32_t
fract
¶ Fractional seconds.
-
std::int16_t
-
class
transaction
¶ - #include <nanodbc.h>
A resource for managing transaction commits and rollbacks.
- Attention
You will want to use transactions if you are doing batch operations because it will prevent auto commits from occurring after each individual operation is executed.
Public Functions
-
transaction
(const class connection &conn)¶ Begin a transaction on the given connection object.
- Post
Operations that modify the database must now be committed before taking effect.
- Exceptions
-
transaction
(const transaction &rhs)¶ Copy constructor.
-
transaction
(transaction &&rhs) noexcept¶ Move constructor.
-
transaction &
operator=
(transaction rhs)¶ Assignment.
-
void
swap
(transaction &rhs) noexcept¶ Member swap.
-
~transaction
() noexcept¶ If this transaction has not been committed, will will rollback any modifying ops.
-
void
commit
()¶ Commits transaction immediately.
- Exceptions
-
void
rollback
() noexcept¶ Marks this transaction for rollback.
-
class connection &
connection
()¶ Returns the connection object.
-
const class connection &
connection
() const¶ Returns the connection object.
-
operator class connection&
()¶ Returns the connection object.
-
operator const class connection&
() const¶ Returns the connection object.
Private Members
-
std::shared_ptr<transaction_impl>
impl_
¶
Friends
- friend class nanodbc::connection
-
class
type_incompatible_error
: public runtime_error¶ - #include <nanodbc.h>
Type incompatible.
- See
Exception types