TTConnection Reference

The TTConnection class encapsulates the concept of a connection to a database. You can think of TTConnection as a value-added C++ wrapper around the ODBC connection handle (SQLHDBC).

Also see TTConnection Usage.

Public Members

Member Description

Member	Description
`DRIVER_COMPLETION_ENUM`	Specifies whether there is a prompt for the database to connect to (also depending on whether a database is specified in the connect string). Valid values are `TTConnection::DRIVER_NOPROMPT`, `TTConnection::DRIVER_COMPLETE`, `TTConnection::DRIVER_PROMPT`, and `TTConnection::DRIVER_COMPLETE_REQUIRED`. These correspond to the values `SQL_DRIVER_NOPROMPT`, `SQL_DRIVER_COMPLETE`, `SQL_DRIVER_PROMPT`, and `SQL_DRIVER_COMPLETE_REQUIRED` for the standard ODBC `SQLDriverConnect` function.

DRIVER_COMPLETION_ENUM

Specifies whether there is a prompt for the database to connect to (also depending on whether a database is specified in the connect string).

Valid values are TTConnection::DRIVER_NOPROMPT, TTConnection::DRIVER_COMPLETE, TTConnection::DRIVER_PROMPT, and TTConnection::DRIVER_COMPLETE_REQUIRED. These correspond to the values SQL_DRIVER_NOPROMPT, SQL_DRIVER_COMPLETE, SQL_DRIVER_PROMPT, and SQL_DRIVER_COMPLETE_REQUIRED for the standard ODBC SQLDriverConnect function.

Public Methods

This section summarizes then describes the TTConnection public methods.

Public Methods Summary

Method	Description
`Commit()`	Commits a transaction to the database.
`Connect()`	Opens a new database connection.
`Disconnect()`	Closes a database connection.
`DurableCommit()`	Performs a durable commit operation on the database.
`getHdbc()`	Returns the ODBC connection handle (type `SQLHDBC`) associated with this connection.
`GetTTContext()`	Returns the connection context value.
`isConnected()`	Returns `TRUE` if the object is connected to TimesTen.
`Rollback()`	Rolls back changes made to the database through this connection since the last call to `Commit()` or `Rollback()`.
`SetAutoCommitOff()`	Disables autocommit for the connection.
`SetAutoCommitOn()`	Enables autocommit for the connection.
`SetIsoReadCommitted()`	Sets the transaction isolation level of the connection to be `TXN_READ_COMMITTED`.
`SetIsoSerializable()`	Sets the transaction isolation level of the connection to be `TXN_SERIALIZABLE`.
`SetLockWait()`	Sets the lock timeout interval for the connection by calling the `ttLockWait` TimesTen built-in procedure.
`SetPrefetchCloseOff()`	Turns off the `TT_PREFETCH_CLOSE` connection option.
`SetPrefetchCloseOn()`	Turns on the `TT_PREFETCH_CLOSE` connection option. This is useful for optimizing `SELECT` query performance for client/server connections to TimesTen.
`SetPrefetchCount()`	Allows a user application to tune the number of rows that the TimesTen ODBC driver `SQLFetch` call prefetches for a `SELECT` statement.

Commit()

void Commit()

Commits a transaction to the database. This commits all operations performed on the connection since the last call to the Commit() or Rollback() method. A TTStatus object is thrown as an exception if an error occurs. Also see Rollback().

Connect()

virtual void Connect(const char* connStr)
virtual void Connect(const char* connStr, const char* username, 
                     const char* password)
virtual void Connect(const char* connStr, DRIVER_COMPLETION_ENUM driverCompletion)

Opens a new database connection. The connection string specified in the connStr parameter is used to create the connection. Specify a user and password, either as part of the connect string or as separate parameters, or a DRIVER_COMPLETION_ENUM value (refer to Public Members). Also see the following method, Disconnect().

Privilege to connect to a database must be granted to users through the CREATE SESSION privilege, either directly or through the PUBLIC role. See Connection Methods.

A TTStatus object is thrown as an exception if an error occurs. Any exception warnings are usually informational and can often be safely ignored. The following logic is preferred for use of the Connect() method.

TTWarning and TTError are subclasses of TTStatus.

TTConnection conn;
...

try {
  conn.Connect("DSN=mydsn", "myuser", "password");
}
catch (TTWarning warn) {
  // warnings from Connect() are usually informational
  cerr << ''Warning while connecting to TimesTen: '' << warn << endl;
}
catch (TTError err) {
  // handle the error; this could be a serious problem
}

Disconnect()

void Disconnect()

Closes a database connection. A TTStatus object is thrown as an exception if an error occurs. Also see the preceding method, Connect().

DurableCommit()

void DurableCommit()

Performs a durable commit operation on the database. A durable commit operation flushes the in-memory transaction log buffer to the file system. It calls the ttDurableCommit TimesTen built-in procedure.

See ttDurableCommit in Oracle TimesTen In-Memory Database Reference.

getHdbc()

SQLHDBC getHdbc()

Returns the ODBC connection handle associated with this connection.

GetTTContext()

void GetTTContext(char* output)

Returns the context value of the connection, a value that is unique for each database connection. The context of a connection can be used to correlate TimesTen connections with PIDs (process IDs) using the ttStatus TimesTen utility, for example.

The context value is returned through the output parameter, which requires an array of CHAR[17] or larger.

This method calls the ttContext TimesTen built-in procedure. See ttContext in Oracle TimesTen In-Memory Database Reference.

isConnected()

bool isConnected()

Returns TRUE if the object is connected to TimesTen using the Connect() method or FALSE if not.

Rollback()

void Rollback()

Rolls back (cancels) a transaction. This undoes any changes made to the database through the connection since the last call to Commit() or Rollback(). A TTStatus object is thrown as an exception if an error occurs. Also see Commit().

SetAutoCommitOff()

void SetAutoCommitOff()

Disables autocommit for the connection. Also see the following method, SetAutoCommitOn().

This method is automatically called by TTConnection::Connect(), because TimesTen runs with optimal performance only with autocommit disabled.

Note that when autocommit is disabled, committing SELECT statements requires explicit calls to TTCmd::Close().

SetAutoCommitOn()

void SetAutoCommitOn()

Enables autocommit for the connection, which means that every SQL statement occurs in its own transaction. Also see the preceding method, SetAutoCommitOff().

SetAutoCommitOn() is generally not advisable, because TimesTen runs much faster with autocommit disabled.

SetIsoReadCommitted()

void SetIsoReadCommitted()

Sets the transaction isolation level of the connection to be TXN_READ_COMMITTED. The Read Committed isolation level offers the best combination of single-transaction performance and good multiconnection concurrency. Also see the following method, SetIsoSerializable().

SetIsoSerializable()

void SetIsoSerializable()

Sets the transaction isolation level of the connection to be TXN_SERIALIZABLE. In general, Serializable isolation level offers fair individual transaction performance but extremely poor concurrency. Read Committed isolation level is preferable over Serializable isolation level in almost all situations. Also see the preceding method, SetIsoReadCommitted().

SetLockWait()

void SetLockWait(int secs)

Sets the lock timeout interval for the connection by calling the ttLockWait TimesTen built-in procedure with the secs parameter. In general, a two-second or three-second lock timeout is sufficient for most applications. The default lock timeout interval is 10 seconds.

See ttLockWait in Oracle TimesTen In-Memory Database Reference.

SetPrefetchCloseOff()

void SetPrefetchCloseOff()

Turns off the TT_PREFETCH_CLOSE connection option. Also see the following method, SetPrefetchCloseOn().

SetPrefetchCloseOn()

void SetPrefetchCloseOn()

Turns on the TT_PREFETCH_CLOSE connection option, which is useful for optimizing SELECT query performance for serializable transactions in client/server applications. Note that this method provides no benefit for an application using a direct connection to TimesTen. Also see the preceding method, SetPrefetchCloseOff().

See Optimizing Query Performance in Oracle TimesTen In-Memory Database C Developer's Guide

SetPrefetchCount()

void SetPrefetchCount(int numrows)

Allows a client/server application to tune the number of rows that the TimesTen ODBC driver internally fetches at a time for a SELECT statement. The value of numrows must be between 1 and 128, inclusive.

Note that this method provides no benefit for an application using a direct connection to TimesTen.

Note:

This method is not equivalent to executing TTCmd::FetchNext() multiple times. Instead, proper use of this parameter reduces the amount of time for each call to TTCmd::FetchNext().

See Prefetching Multiple Rows of Data in Oracle TimesTen In-Memory Database C Developer's Guide for more information about TT_PREFETCH_COUNT.