Manages and encapsulates ODBC resources such as the connection and environment handles. More...

#include <nanodbc.h>

Public Member Functions
	connection ()
	Create new connection object, initially not connected.

	connection (const connection &rhs) noexcept
	Copy constructor.

	connection (connection &&rhs) noexcept
	Move constructor.

connection &	operator= (connection rhs) noexcept
	Assignment.

void	swap (connection &) noexcept
	Member swap.

	connection (string const &dsn, string const &user, string const &pass, long timeout=0)
	Create new connection object and immediately connect to the given data source.

	connection (string const &connection_string, long timeout=0)
	Create new connection object and immediately connect using the given connection string.

	~connection () noexcept
	Automatically disconnects from the database and frees all associated resources.

void	allocate ()
	Allocate environment and connection handles.

void	deallocate ()
	Release environment and connection handles.

void	connect (string const &dsn, string const &user, string const &pass, long timeout=0)
	Connect to the given data source.

void	connect (string const &connection_string, long timeout=0)
	Connect using the given connection string.

bool	async_connect (string const &dsn, string const &user, string const &pass, void *event_handle, long timeout=0)
	Initiate an asynchronous connection operation to the given data source.

bool	async_connect (string const &connection_string, void *event_handle, long timeout=0)
	Initiate an asynchronous connection operation using the given connection string.

void	async_complete ()
	Completes a previously initiated asynchronous connection operation.

bool	connected () const noexcept
	Returns true if connected to the database.

void	disconnect ()
	Disconnects from the database, but maintains environment and handle resources.

std::size_t	transactions () const noexcept
	Returns the number of transactions currently held for this connection.

void *	native_dbc_handle () const noexcept
	Returns the native ODBC database connection handle.

void *	native_env_handle () const noexcept
	Returns the native ODBC environment handle.

template<class T >
T	get_info (short info_type) const
	Returns information from the ODBC connection as a string or fixed-size value.

string	dbms_name () const
	Returns name of the DBMS product.

string	dbms_version () const
	Returns version of the DBMS product.

string	driver_name () const
	Returns the name of the ODBC driver.

string	driver_version () const
	Returns the version of the ODBC driver.

string	database_name () const
	Returns the name of the currently connected database.

string	catalog_name () const
	Returns the name of the current catalog.

Detailed Description

Manages and encapsulates ODBC resources such as the connection and environment handles.

Constructor & Destructor Documentation

◆ connection() [1/2]

nanodbc::connection::connection	(	string const &	dsn,
		string const &	user,
		string const &	pass,
		long	timeout = `0`
	)

Create new connection object and immediately connect to the given data source.

The function calls ODBC API SQLConnect.

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

database_error

See also: connected(), connect()

◆ connection() [2/2]

nanodbc::connection::connection	(	string const &	connection_string,
		long	timeout = `0`
	)

explicit

Create new connection object and immediately connect using the given connection string.

The function calls ODBC API SQLDriverConnect.

Parameters

connection_string	The connection string for establishing a connection.
timeout	Seconds before connection timeout. Default is 0 indicating no timeout.

Exceptions

database_error

See also: connected(), connect()

◆ ~connection()

nanodbc::connection::~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.

Member Function Documentation

◆ allocate()

void nanodbc::connection::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.

Exceptions

database_error

See also: deallocate()

◆ deallocate()

void nanodbc::connection::deallocate ( )

Release environment and connection handles.

See also: allocate()

◆ connect() [1/2]

void nanodbc::connection::connect	(	string const &	dsn,
		string const &	user,
		string const &	pass,
		long	timeout = `0`
	)

Connect to the given data source.

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

database_error

See also: connected()

◆ connect() [2/2]

void nanodbc::connection::connect	(	string const &	connection_string,
		long	timeout = `0`
	)

Connect using the given connection string.

Parameters

connection_string	The connection string for establishing a connection.
timeout	Seconds before connection timeout. Default is 0 indicating no timeout.

Exceptions

database_error

See also: connected()

◆ async_connect() [1/2]

bool nanodbc::connection::async_connect	(	string const &	dsn,
		string const &	user,
		string const &	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 and SQLCompleteAsync 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.

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

database_error

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

See also: connected()

◆ async_connect() [2/2]

bool nanodbc::connection::async_connect	(	string const &	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 and SQLCompleteAsync 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.

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

database_error

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

See also: connected()

◆ async_complete()

void nanodbc::connection::async_complete ( )

Completes a previously initiated asynchronous connection operation.

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

◆ get_info()

template<class T >

T nanodbc::connection::get_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.

◆ dbms_name()

string nanodbc::connection::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.

◆ dbms_version()

string nanodbc::connection::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.

◆ driver_name()

string nanodbc::connection::driver_name ( ) const

Returns the name of the ODBC driver.

Exceptions

database_error

◆ driver_version()

string nanodbc::connection::driver_version ( ) const

Returns the version of the ODBC driver.

Exceptions

database_error

◆ database_name()

string nanodbc::connection::database_name ( ) const

Returns the name of the currently connected database.

Returns the current SQL_DATABASE_NAME information value associated with the connection.

◆ catalog_name()

string nanodbc::connection::catalog_name ( ) const

Returns the name of the current catalog.

Returns the current setting of the connection attribute SQL_ATTR_CURRENT_CATALOG.

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

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

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ connection() [1/2]

◆ connection() [2/2]

◆ ~connection()

Member Function Documentation

◆ allocate()

◆ deallocate()

◆ connect() [1/2]

◆ connect() [2/2]

◆ async_connect() [1/2]

◆ async_connect() [2/2]

◆ async_complete()

◆ get_info()

◆ dbms_name()

◆ dbms_version()

◆ driver_name()

◆ driver_version()

◆ database_name()

◆ catalog_name()