The ITConnection class

Base class: ITErrorManager

Manages a connection to a database and the errors that can occur. The ITConnection class is used to open a connection to the database server and to manage error objects and transaction states.

Only one result set can be outstanding on a DataBlade® API connection. The encapsulates DataBlade API connection serialization through check-out (with ITConnection::CheckOutConn()) and check-in (with ITConnection::CheckInConn()). The ITQuery, ITStatement, and ITCursor methods that perform server access (for example, ITQuery::ExecToSet() and ITCursor::Prepare()) check out the connection, perform the operation, and then check the connection in. ITQuery::ExecForIteration() checks out the connection for the duration of the results retrieval. Some operations (for example, large object operations and server routine execution) might require server access but do not affect the results set. These operations use ITConnection::GetConn() to get the DataBlade API connection without checking it out.

Applications generally do not need to use the DataBlade API connection directly. Value objects do not attempt to perform the operations that would require checking the connection out (it is likely to be checked out by the query object). Value objects can use the DataBlade API connection obtained by calling ITConnection::GetConn() to perform the operations that do not require connection checkout. Value objects gracefully handle the possibility of ITConnection::GetConn() returning NULL (when the connection is not open).

The following table lists the methods provided by this class.


Method	Description
ITConnection()	Creates an unconnected connection object with the default DBInfo.
ITConnection(MI_CONNECTION *, enum ITTransactionState tstate)	Constructs a connection object for an existing connection and sets the transaction state with the provided argument.
ITBool SetDBInfo(const ITDBInfo &)	Sets the DBInfo of the connection without opening the connection. Returns `TRUE` if successful; `FALSE` if the connection is currently open.
ITBool Open(const ITDBinfo &db)	Opens the connection with the specified DBInfo.
ITBOOL Open()	Opens the connection with the default DBInfo.
ITBool Close()	Closes the database connection.
ITBool IsOpen() const	Returns `TRUE` if the connection is open, `FALSE` if it is not.
MI_CONNECTION *GetConn()	Returns DataBlade API connection encapsulated by ITConnection object, `NULL` if ITConnection is not open.
ITBool SetTransaction(enum ITTransactionState, ITCallBackFuncPtr func=NULL, void *userdata=NULL)	Sets the transaction state. The transaction state can be set to Begin to begin the transaction, or Commit or Abort to finish it. See Connection transaction states for more information. The CallBackFuncPtr and user data arguments are reserved for future use. The transaction states are: ITTransactionState::NONE ITTransactionState::AUTO ITTransactionState::BEGIN ITTransactionState::COMMIT ITTransactionState::ABORT
enum ITTransactionState GetTransactionState()	Returns the transaction state.
MI_CONNECTION *CheckOutConn()	Checks out the DataBlade API connection handle in order to bypass this C++ interface. Returns `NULL` if the connection is already checked out or the ITConnection is not connected to a database. Restriction: This interface is for compatibility with DataBlade API. Direct use of the DataBlade API is discouraged.
ITBool CheckInConn()	Returns a checked-out DataBlade API connection to the ITConnection. Returns `TRUE` if the connection was previously checked out, `FALSE` otherwise.
const ITConnectionStamp &GetStamp()	Gets the current connection stamp object. (For details, see The ITConnectionStamp class.)
const ITDBInfo &GetDBInfo()	Retrieves the DBInfo object information with which the connection was initialized.