Made to Order Software Corporation Logo

odbcpp: odbcpp::handle Class Reference

Manage an ODBC handle. More...

#include <handle.h>

Inheritance diagram for odbcpp::handle:
Collaboration diagram for odbcpp::handle:

List of all members.

Public Member Functions

SQLRETURN check (SQLRETURN return_code, handle *parent=0) const
 Check the return code of an SQL function call.

const diagnosticget_diagnostic () const
 Get a reference to the current diagnostic of this handle.

SQLHANDLE get_handle () const
 Retrieve the SQL handle.

SQLSMALLINT get_handle_type () const
 Retrieve the type of handle.

 handle (SQLSMALLINT handle_type)
 Initialize the low level handle.

 ~handle ()
 Clean up the handle.

Protected Attributes

SQLHANDLE f_handle
 The ODBC handle.

const SQLSMALLINT f_handle_type
 The type of the ODBC handle.

Private Member Functions

 handle (const handle &hdl)
 Cannot copy handles, really, won't work!

handleoperator= (const handle &hdl)
 Cannot copy handles, really, won't work!

Private Attributes

diagnostic f_diag
 The last command diagnostics.


Detailed Description

Manage an ODBC handle.

This class is the base class for the environment, the connection and the statement classes. It holds the object handle and manages the errors.

The handle needs to be allocated by the derived class constructor or other functions will not behave as expected. Especially, the handle destructor expects the f_handle variable member to always be defined.

The check() function is the one used to make sure that all errors are being handled.

Parameters:
[in] handle_type The SQL handle type (i.e. SQL_HANDLE_ENV)
See also:
check()

Definition at line 33 of file handle.h.


Constructor & Destructor Documentation

odbcpp::handle::handle ( SQLSMALLINT  handle_type  ) 

Initialize the low level handle.

This function initialize the handle as expected.

At the start, the handle pointer is set to NULL. The super class must define that handle in its constructor.

Definition at line 131 of file handle.cpp.

odbcpp::handle::~handle (  ) 

Clean up the handle.

This function will free the handle as expected.

If it is necessary to have a function called before the handle can be freed, it needs to be done in the desctructor of the specific handle.

For instance, the connection handle needs to get disconnected first.

Definition at line 150 of file handle.cpp.

References f_handle, and f_handle_type.

odbcpp::handle::handle ( const handle hdl  )  [inline, private]

Cannot copy handles, really, won't work!

Definition at line 51 of file handle.h.


Member Function Documentation

SQLRETURN odbcpp::handle::check ( SQLRETURN  return_code,
handle parent = 0 
) const

Check the return code of an SQL function call.

This function checks the return code of an SQL function called on this handle. If the return code represents an error, then an odbcpp_error is thrown.

In all cases, a diagnostic is generated.

The following is how this function is usually used:

        check(SQLExecDirect( ... ));

And yes, that means most of the necessary error handling is done in this function.

If the function may return a code that needs special handling such as SQL_NO_DATA returned by SQLFetch(), then you should test the code before calling the check() function.

Parameters:
[in] return_code The code returned by an SQL function
[in] parent The parent handle when allocating a child handle
Returns:
A copy of the return_code parameter

Definition at line 184 of file handle.cpp.

References f_diag, f_handle, and f_handle_type.

Referenced by odbcpp::statement::cancel(), odbcpp::statement::close_cursor(), odbcpp::statement::cols(), odbcpp::environment::commit(), odbcpp::connection::commit(), odbcpp::connection::connect(), odbcpp::connection::connection(), odbcpp::connection::disconnect(), odbcpp::environment::environment(), odbcpp::statement::execute(), odbcpp::statement::fetch(), odbcpp::environment::get_data_source(), odbcpp::environment::rollback(), odbcpp::connection::rollback(), odbcpp::statement::rows(), odbcpp::statement::set_attr(), odbcpp::environment::set_attr(), odbcpp::connection::set_attr(), and odbcpp::statement::statement().

odbcpp::handle::get_diagnostic (  )  const [inline]

Get a reference to the current diagnostic of this handle.

Each time an ODBC function is called, a diagnostic is generated. Some of these diagnostics are saved in the handle diagnostic variable member that can be retrieved using this function.

The diagnostics hold information such as the last error or warning and the number of rows affected by the last executed SQL statement.

Returns:
A reference to the handle diagnostic.

Definition at line 43 of file handle.h.

References f_diag.

odbcpp::handle::get_handle (  )  const [inline]

Retrieve the SQL handle.

This function lets you retrieve the SQL handle.

Bug:
Be careful, by getting and using the SQL handle directly you may change the internal state without the odbcpp library knowing and thus later have it generate unexpected errors.
Returns:
The SQL handle

Definition at line 41 of file handle.h.

References f_handle.

Referenced by odbcpp::diagnostic::diagnostic().

odbcpp::handle::get_handle_type (  )  const [inline]

Retrieve the type of handle.

This function returns the type of handle as specified at the time the handle is constructed (it cannot be changed at a later time.)

The returned value is the untranslated ODBC type.

Returns:
The ODBC type of this handle.

Definition at line 42 of file handle.h.

References f_handle_type.

Referenced by odbcpp::diagnostic::diagnostic().

handle& odbcpp::handle::operator= ( const handle hdl  )  [inline, private]

Cannot copy handles, really, won't work!

Definition at line 53 of file handle.h.


Member Data Documentation

odbcpp::handle::f_diag [mutable, private]

The last command diagnostics.

Whenever a command is called, its diagnostics are saved in this variable.

A reference to the diagnostics can be retrieved using the handle::get_diagnostic() function.

A diagnostic is accessible in an exception when one is generated.

Definition at line 55 of file handle.h.

Referenced by check(), and get_diagnostic().

The type of the ODBC handle.

This variable member holds the type of the handle.

Notice that it is defined at construction time and it is read-only and thus it cannot be changed (in effect, it is hard coded.)

This is the type as defined in the ODBC header files.

Definition at line 47 of file handle.h.

Referenced by check(), odbcpp::environment::commit(), odbcpp::connection::commit(), odbcpp::connection::connection(), odbcpp::environment::environment(), get_handle_type(), odbcpp::environment::rollback(), odbcpp::connection::rollback(), odbcpp::statement::statement(), and ~handle().


The documentation for this class was generated from the following files:
Generated on Mon Sep 19 12:52:28 2011 for odbcpp by  doxygen 1.6.3