3 Class Descriptions

disableLogging()

static void disableLogging()

This method disables all TTClasses logging. Note that the following two statements are identical:

TTGlobal::disableLogging();  
TTGlobal::setLogLevel(TTLog::TTLOG_NIL);

setLogLevel()

static void setLogLevel(TTLog::TTLOG_LEVEL level)

This method specifies the verbosity level of TTClasses logging. Table 3-1 describes TTClasses logging levels. The levels are cumulative.

To set the logging level to TTLog::TTLOG_ERR, for example, add the following line to your program:

TTGlobal::setLogLevel(TTLog::TTLOG_ERR);

setLogStream()

static void setLogStream(ostream& stream)

Specifies where TTClasses logging information should be sent. By default, if TTClasses logging is enabled, logging is to stderr. Using this method, an application can specify logging to a file (or any other ostream&), such as in the following example that sets logging to app_log.txt:

ofstream log_file("app_log.txt");
TTGlobal::setLogStream(log_file);

sqlhenv()

static SQLHENV sqlhenv()

Retrieves the underlying ODBC environment object.

TTError

TTError is a subclass of TTStatus and is used to encapsulate ODBC errors (return codes SQL_ERROR and SQL_INVALID_HANDLE).

TTWarning

TTWarning is a subclass of TTStatus and is used to encapsulate ODBC warnings (return code SQL_SUCCESS_WITH_INFO).

ODBC warnings (the Return Receipt warning, for example) are usually not as serious as ODBC errors and should typically be handled with different logic. ODBC errors should be handled programmatically. There may be circumstances where handling ODBC warnings programmatically is warranted, but it is usually sufficient to simply log them.

Example 3-3 shows usage of the TTError and TTWarning subclasses.

// catching TTError & TTWarning exceptions

try {
  // some TTClasses method calls
}
catch (TTWarning warn) {
  cerr << "Warning encountered: " << warn << endl;
}
catch (TTError err) {
  // handle the error; this could be a serious problem
}

isConnectionInvalid()

bool isConnectionInvalid() const

Returns TRUE if the database connection is invalid, or FALSE if it is valid. Specifically, "invalid" refers to situations when a TimesTen error 846 or 994 is encountered. See "Errors 0 - 999" in Oracle TimesTen In-Memory Database Error Messages and SNMP Traps for information about those errors.

ostream()

friend ostream& operator<<(ostream&, TTStatus& stat)

This method prints the error to a stream.

throwError()

void throwError()

This is an alternative, but not typical, way to throw an exception. In most cases the following two blocks of code are equivalent, but the former is more typical.

try {
  // ...
  if (/* something has gone wrong */)
    throw stat;
}
catch (TTStatus st) {
  cerr << "Caught exception: " << st << endl;
}

Or:

try {
  // ...
  if (/* something has gone wrong */)
    stat.throwError();
}
catch (TTStatus st) {
  cerr << "Caught exception: " << st << endl;
}

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 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 "Access control for connections".

TTConnection conn;
...

try {
  conn.Connect("DSN=mydsn", "myuser", "mypassword");
}
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 Connect().

DurableCommit()

void DurableCommit()

Performs a durable commit operation on the database. A durable commit operation flushes the in-memory transaction log buffer to disk. 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 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 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 SetIsoSerializable(), following.

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 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 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 SetPrefetchCloseOff().

See "Enable TT_PREFETCH_CLOSE for Serializable transactions" in Oracle TimesTen In-Memory Database Operations 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.

See "Prefetching multiple rows of data" in Oracle TimesTen In-Memory Database C Developer's Guide for more information about TT_PREFETCH_COUNT.

AddConnectionToPool()

int AddConnectionToPool(TTConnection* connP)

This method is used to add a TTConnection object (possibly an object of a class derived from TTConnection) to the connection pool. It returns -1 if there is an error. Also see freeConnection().

ConnectAll()

void ConnectAll(const char* connStr)
void ConnectAll(const char* connStr, const char* username, const char* password)

After all the TTConnection objects of an application have been added to the connection pool by AddConnectionToPool(), the ConnectAll() method can be used to connect all of the TTConnection objects to TimesTen simultaneously. 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. Also see DisconnectAll().

A TTStatus object is thrown as an exception if an error occurs.

Privilege to connect to a database must be granted to users through the CREATE SESSION privilege, either directly or through the PUBLIC role. See "Access control for connections".

DisconnectAll()

void DisconnectAll()

Disconnects all connections in the connection pool from TimesTen. Also see ConnectAll().

Applications must call DisconnectAll() before termination to avoid overhead associated with process failure analysis and recovery. A TTStatus object is thrown as an exception if an error occurs.

freeConnection()

void freeConnection(TTConnection* connP)

Returns a connection to the pool for reassignment to another thread. Applications should not free connections that are in the middle of a transaction. TTConnection::Commit() or Rollback() should be called immediately before the TTConnection object is passed to freeConnection(). Also see AddConnectionToPool().

getConnection()

TTConnection* getConnection(int timeout_millis=0)

Checks out an idle connection from the connection pool for use by a thread. A pointer to an idle TTConnection object is returned. The thread should then perform a transaction, ending with either Commit() or Rollback(), and then should return the connection to the pool using the freeConnection() method.

If no idle connections are in the pool, the thread calling getConnection() blocks until a connection is returned to the pool by a call to freeConnection(). An optional timeout, in milliseconds, can be provided. If this is provided, getConnection() waits for a free connection for no more than timeout_millis milliseconds. If no connection is available in that time then getConnection() returns NULL to the caller.

getStats()

void getStats(int* nGets, int* nFrees, int* nWaits, int* nTimeouts,
              int* maxInUse, int* nForcedCommits)

Queries the TTConnectionPool for status information. The following data are returned:

• nGets: Number of calls to getConnection()

• nFrees: Number of calls to freeConnection()

• nWaits: Number of times a call to getConnection() had to wait before returning a connection

• nTimeouts: Number of calls to getConnection() that timed out

• maxInUse: High point for the most number of connections in use simultaneously

• nForcedCommits: Number of times that freeConnection() had to call Commit() on a connection before checking it into the pool

  If this counter is nonzero, the user application is not calling TTConnection::Commit() or Rollback() before returning a connection to the pool.

Close()

void Close()

If a SQL SELECT statement is executed using the Execute() method, a cursor is opened which may be used to fetch rows from the result set. When the application is finished fetching rows from the result set, it must be closed with the Close() method.

Failure to close the result set may result in locks being held on rows for too long, causing concurrency problems, memory leaks, and other errors.

A TTStatus object is thrown as an exception if an error occurs.

Drop()

void Drop()

If a prepared SQL statement will not be used in the future, the statement and resources associated with it can be freed by a call to the Drop() method. The TTCmd object may be reused for another statement if Prepare() is called again.

It is more efficient to use multiple TTCmd objects to execute multiple SQL statements. Use the Drop() method only if a particular SQL statement will not be used again.

A TTStatus object is thrown as an exception if an error occurs.

Execute()

void Execute()

This method invokes a SQL statement that has been prepared for execution with the Prepare() method, after any necessary parameter values are defined using setParam() calls. A TTStatus object is thrown as an exception if an error occurs.

If the SQL statement is a SELECT statement, this method executes the query but does not return any rows from the result set. Use the FetchNext() method to fetch rows from the result set one at a time. Use the Close() method to close the result set when all appropriate rows have been fetched. For SQL statements other than SELECT, no cursor is opened, and a call to the Close() method is not necessary.

TimesTen has features to control database access with object-level resolution for database objects such as tables, views, materialized views, sequences, and synonyms. Access control privileges are checked both when SQL is prepared and when it is executed in the database, with most of the performance cost coming at prepare time. See "Considering TimesTen features for access control".

ExecuteImmediate()

int ExecuteImmediate(TTConnection* cP, const char* sqlp)

This method invokes a SQL statement that has not been previously prepared.

ExecuteImmediate() is a convenient alternative to using Prepare() and Execute() when a SQL statement is to be executed only a small number of times. Use ExecuteImmediate() for DDL statements such as CREATE TABLE and DROP TABLE, and infrequently used DML statements that do not return a result set (for example, DELETE FROM table_name).

ExecuteImmediate() is incompatible with SQL statements that return a result set. In addition, statements executed through ExecuteImmediate() cannot subsequently be queried by getRowCount() to get the number of rows affected by a DML operation. Because of this, ExecuteImmediate() calls getRowCount() automatically, and its value is the integer return value of this method.

A TTStatus object is thrown as an exception if an error occurs.

FetchNext()

int FetchNext()

After executing a prepared SQL SELECT statement using the Execute() method, use the FetchNext() method to fetch rows from the result set, one at a time.

After fetching a row of the result set, use the appropriate overloaded getColumn() method to fetch values from the current row.

If no more rows remain in the result set, FetchNext() returns 1. If a row is returned, FetchNext() returns 0.

After executing a SELECT statement using the Execute() method, the result set must be closed using the Close() method after all desired rows have been fetched. Note that after the Close() method is called, the FetchNext() method cannot be used to fetch additional rows from the result set.

A TTStatus object is thrown as an exception if an error occurs.

getColumn()

void getColumn (int cno, TYPE* valueP)
void getColumn (int cno, TYPE* valueP, int* byteLenP)

The getColumn() method, as well as the getColumnNullable() method, fetches the values for columns of the current row of the result set. Before getColumn() or getColumnNullable() can be called, the FetchNext() method must be called to fetch the next (or first) row from the result set of a SELECT statement. SQL statements are executed using the Execute() method.

Each getColumn() call retrieves the value associated with a particular column. Columns are referred to by ordinal number, with "1" indicating the first column specified in the SELECT statement. In all cases the first argument passed to the getColumn() method, cno, is the ordinal number of the column whose value is to be fetched. The second argument, valueP, is a pointer to a variable that stores the value of the specified column. The type of this argument varies depending on the type of the column being returned. For NCHAR, NVARCHAR, and binary types, as shown in the table, the method call also specifies byteLenP, a pointer to an integer value for the number of bytes written into the valueP buffer.

The TTClasses library does not support a large set of data type conversions. The appropriate version of getColumn() must be called for each output column in the prepared SQL. Calling the wrong version, such as attempting to fetch an integer column into a char* value, results in a thrown exception (TTStatus object).

When fetching integer-type data from NUMBER columns, getColumn() supports the following variants: SQLTINYINT, SQLSMALLINT, SQLINTEGER, and SQLBIGINT. They are appropriate only for NUMBER fields with the scale parameter set to zero, such as NUMBER(p) or NUMBER(p,0). The functions have the following range of precision.

To ensure that all values in the column fit into the variable that the application uses to retrieve information from the database, you can use SQLBIGINT for all table columns of data type NUMBER(p), where 0 <= p <= 18. For example:

getColumn(int cno, SQLBIGINT* iP)

Table 3-2 shows the supported TimesTen column types and the appropriate versions of getColumn() and getColumnNullable() to use for each parameter type.

getColumn(cno, SQLTINYINT* iP)

getColumn(cno, SQLSMALLINT* iP)

getColumn(cno, SQLINTEGER* iP)

getColumn(cno, SQLBIGINT* iP)

getColumn(cno, float* fP)

getColumn(cno, double* dP)

getColumn(cno, char** cPP)

getColumn(cno, char* cP)

getColumn(cno, SQLTINYINT* iP)

getColumn(cno, SQLSMALLINT* iP)

getColumn(cno, SQLINTEGER* iP)

getColumn(cno, SQLBIGINT* iP)

getColumn(cno, char** cPP)

getColumn(cno, char* cP)

getColumn(cno, SQLWCHAR** wcPP)

getColumn(cno, SQLWCHAR** wcPP, byteLenP)

getColumn(cno, void** binPP, byteLenP)

getColumn(cno, void* binP, byteLenP)

getColumn(cno, TIMESTAMP_STRUCT* tsP)

getColumn(cno, DATE_STRUCT* dP)

getColumn(cno, TIME_STRUCT* tP)

Other TimesTen table column types are not supported in this release of the TTClasses library.

getColumnLength()

int getColumnLength(int cno)

Returns the length, in bytes, of the value in column number cno of the current row, not counting the NULL terminator. Or it returns SQL_NULL_DATA if the value is NULL. (For those familiar with ODBC, this is the value stored by ODBC in the last parameter, pcbValue, from SQLBindCol after a call to SQLFetch.) When there is a non-null value, the length returned is between 0 and the column precision, inclusive. See getColumnPrecision().

For example, assume a VARCHAR2(25) column. If the value is null, the length returned is -1. If the value is 'abcde', the length returned is 5.

This method is generally useful only when accessing columns of type CHAR, VARCHAR2, NCHAR, NVARCHAR2, BINARY, and VARBINARY.

getColumnNullable()

bool getColumnNullable(int cno, TYPE* valueP)
bool getColumnNullable(int cno, TYPE* valueP, int* byteLenP)

The getColumnNullable() method is similar to the getColumn() method and supports the same data types and signatures as documented in Table 3-2 above. However, in addition to the behavior of getColumn(), the getColumnNullable() method also returns a boolean indicating whether the value is the SQL NULL pseudo-value. If the value is NULL, the second parameter is set to a distinctive value (for example, -9999) and the return value from the method is TRUE. If the value is not NULL, it is returned through the variable pointed to by the second parameter and the getColumnNullable() method returns FALSE.

getHandle()

SQLHSTMT getHandle()

If you must manipulate the underlying ODBC statement object, use this method to retrieve the statement handle.

getMaxRows()

int getMaxRows()

This method returns the current limit of the number of rows returned by a SELECT statement from this TTCmd object. A return value of 0 means all rows are returned. Also see setMaxRows().

getNextColumn()

void getNextColumn(TYPE* valueP)
void getNextColumn(TYPE* valueP, int* byteLenP)

The getNextColumn() method, as well as the getNextColumnNullable() method, fetches the value of the next column of the current row of the result set. Before getNextColumn() or getNextColumnNullable() can be called, the FetchNext() method must be called to fetch the next (or first) row from the result set of a SELECT statement. When you use getNextColumn(), the columns are fetched in order. You cannot change the fetch order.

See Table 3-2 for the supported SQL data types and the appropriate method version to use for each data type. This information can be used for getNextColumn(), except there is no column number parameter for getNextColumn().

getNextColumnNullable()

bool getNextColumnNullable(TYPE* valueP)
bool getNextColumnNullable(TYPE* valueP, int* byteLenP)

The getNextColumnNullable() method is similar to the getNextColumn() method. However, in addition to the behavior of getNextColumn(), the getNextColumnNullable() method returns a boolean indicating whether the value is the SQL NULL pseudo-value. If the value is NULL, the second parameter is set to a distinctive value (for example, -9999) and the return value from the method is TRUE. If the value is not NULL, it is returned through the variable pointed to by the second parameter, and the method returns FALSE. When you use getNextColumnNullable(), the columns are fetched in order. You cannot change the fetch order.

See Table 3-2 for the supported SQL data types and the appropriate method versions to use for each data type. This information can be used for getNextColumnNullable(), except there is no column number parameter for getNextColumnNullable().

getParam()

bool getParam(int pno, TYPE* valueP)
bool getParam(int pno, TYPE* valueP, int* byteLenP)

Each getParam() version is used to retrieve the value of an output or input/output parameter, specified by parameter number, after executing a prepared SQL statement. SQL statements are prepared before use with the Prepare() method and are executed with the Execute() method. The getParam() method is used to provide a variable of appropriate data type for the value for each output parameter after executing the statement.

The first argument passed to getParam() is the position of the parameter for the output value. The first parameter in a SQL statement is parameter 1. The second argument passed to getParam() is a variable for the output value. Overloaded versions of getParam() take different data types for the second argument.

The getParam() method supports the same data types documented for getColumn() in Table 3-2. For NCHAR, NVARCHAR, and binary types, as shown in that table, the method call specifies byteLenP, a pointer to an integer value for the number of bytes in the parameter value.

The getParam() return is a boolean that is TRUE if the parameter value is NULL, or FALSE otherwise.

The TTClasses library does not support a large set of data type conversions. The appropriate overloaded version of getParam() must be called for each output parameter in the prepared SQL. Calling the wrong version (attempting to use an integer parameter for a char* value, for example) may result in program failure.

See "Binding output or input/output parameters" for examples using getParam().

For REF CURSORs, the following signature is supported to use a TTCmd object as a statement handle for the REF CURSOR (data type SQL_REFCURSOR). See "Working with REF CURSORs" for information and an example.

bool getParam(int pno, TTCmd** rcCmd)

getQueryThreshold()

int getQueryThreshold()

Returns the threshold value for the TTCmd object, as described in "setQueryThreshold()".

If no value has been set with setQueryThreshold(), this method returns the value of the ODBC connection option TT_QUERY_THRESHOLD (if set) or of the TimesTen general connection attribute QueryThreshold.

getRowCount()

int getRowCount()

This method can be called immediately after Execute() to return the number of rows that were affected by the executed SQL operation. For example, after execution of a DELETE statement that deletes 10 rows, getRowCount() returns 10.

isColumnNull()

bool isColumnNull(int cno)

This method provides another way to determine whether the value in column number cno of the current row is NULL, returning TRUE if so, or FALSE otherwise.

Also see information about the getColumnNullable() method.

Prepare()

void Prepare(TTConnection* cP, const char* sqlp)

This method associates a SQL statement with the TTCmd object. It takes two parameters:

• A pointer to a TTConnection object

  The connection object should be connected to the database by a call to TTConnection::Connect().

• A const char* parameter for the SQL statement being prepared

TimesTen has features to control database access with object-level resolution for database objects such as tables, views, materialized views, sequences, and synonyms. Access control privileges are checked both when SQL is prepared and when it is executed in the database, with most of the performance cost coming at prepare time. See "Considering TimesTen features for access control".

printColumn()

void printColumn(int cno, STDOSTREAM& os, const char*  nullString) const

This method prints the value in column number cno of the current row to the output stream os. Use this for debugging or for demo programs. Use nullString to specify what should be printed if the column value is NULL (for example, "NULL" or "?").

registerParam()

void registerParam(int pno, TTCMD_PARAM_INPUTOUTPUT_TYPE inputOutputType,
                   int sqltype)
void registerParam(int pno, TTCMD_PARAM_INPUTOUTPUT_TYPE inputOutputType, 
                   int sqltype, int precision)
void registerParam(int pno, TTCMD_PARAM_INPUTOUTPUT_TYPE inputOutputType, 
                   int sqltype, int precision, int scale)

Use this method to register a parameter for binding. This is required for output and input/output parameters and can also be used as appropriate to specify SQL type, precision (maximum number of digits that are used by the data type, where applicable), and scale (maximum number of digits to the right of the decimal point, where applicable). See "Registering parameters".

RePrepare()

void RePrepare(TTConnection* cP)

This method prepares the statement again. It is useful only when a statement handle in a prepared statement has been invalidated, such as when a table referenced by the SQL statement has been altered, for example. Also see Prepare().

setMaxRows()

void setMaxRows(const int nMaxRows)

This method sets a limit on the number of rows returned by a SELECT statement. If the number of rows in the result set exceeds the set limit, the TTCmd::FetchNext() method returns 1 when it has fetched the last row in the requested set size. Also see getMaxRows().

The default is to return all rows. To reset a limit to again return all rows, call setMaxRows() with nMaxRows set to 0. The limit is only meaningful for SELECT statements.

setParam()

void setParam(int pno, TYPE value)
void setParam(int pno, TYPE* valueP)
void setParam(int pno, TYPE* valueP, int byteLen)

All overloaded setParam() versions are described in this section.

Each setParam() version is used to set the value of a parameter, specified by parameter number, before executing a prepared SQL statement. SQL statements are prepared before use with the Prepare() method and are executed with the Execute() method. If the SQL statement contains any parameter markers (the "?" character used where a literal constant would be legal), values must be assigned to these parameters before the SQL statement can be executed. The setParam() method is used to define a value for each parameter before executing the statement. See "Dynamic parameters" in Oracle TimesTen In-Memory Database SQL Reference.

The first argument passed to setParam() is the position of the parameter to be set. The first parameter in a SQL statement is parameter 1. The second argument passed to setParam() is the value of the parameter. Overloaded versions of setParam() take different data types for the second argument.

The TTClasses library does not support a large set of data type conversions. The appropriate overloaded version of setParam() must be called for each parameter in the prepared SQL. Calling the wrong version (attempting to set an integer parameter to a char* value, for example) may result in program failure.

Values passed to setParam() are copied into internal buffers maintained by the TTCmd object. These buffers are statically allocated and bound by the Prepare() method. The parameter value is the value passed into setParam() at the time of the setParam() call, not the value at the time of a subsequent Execute() method call.

Table 3-3 shows the supported SQL data types and the appropriate versions of setParam() to use for each type. SQL data types not mentioned are not supported in this version of TTClasses. For NCHAR, NVARCHAR, and binary types, as shown in the table, the method call specifies byteLen, an integer value for the number of bytes in the parameter value.

See "Binding input parameters" and "Binding output or input/output parameters" for examples using setParam(). See "Binding duplicate parameters" regarding duplicate parameters and the difference between TimesTen mode and Oracle mode in handling them.

setParam(pno, SQLTINYINT value)

setParam(pno, SQLSMALLINT value)

setParam(pno, SQLINTEGER value)

setParam(pno, SQLBIGINT value)

setParam(pno, float value)

setParam(pno, double value)

setParam(pno, char* valueP)

setParam(pno, const char* valueP)

setParam(pno, SQLCHAR* valueP)

setParam(pno, SQLTINYINT value)

setParam(pno, SQLSMALLINT value)

setParam(pno, SQLINTEGER value)

setParam(pno, SQLBIGINT value)

setParam(pno, char* valueP)

setParam(pno, const char* valueP)

setParam(pno, SQLCHAR* valueP)

setParam(pno, SQLWCHAR* valueP, byteLen)

setParam(pno, const void* valueP, byteLen)

setParam(pno, TIMESTAMP_STRUCT* valueP)

setParam(pno, DATE_STRUCT* valueP)

setParam(pno, TIME_STRUCT* valueP)

setParamLength()

(Version for non-batch operations)

void setParamLength(int pno, int byteLen)

Sets the length, in bytes, of the bound value for an input parameter specified by parameter number, before execution of the prepared statement.

setParamNull()

(Version for non-batch operations)

void setParamNull(int pno)

Sets a value of SQL NULL for a bound input parameter specified by parameter number.

setQueryThreshold()

void setQueryThreshold(const int nSecs)

Use this method to specify a threshold time limit, in seconds, for the TTCmd object. (This applies to any SQL statement, not just queries.) If the execution time of a statement exceeds the threshold, a warning is written to the support log and an SNMP trap is thrown. Execution continues and is not affected by the threshold. Also see "getQueryThreshold()".

The setQueryThreshold() method has the same effect as using SQLSetStmtOption to set TT_QUERY_THRESHOLD or setting the TimesTen general connection attribute QueryThreshold.

See "Setting a timeout or threshold for executing SQL statements".

setQueryTimeout()

void setQueryTimeout(const int nSecs)

Use this method to specify how long, in seconds, any SQL statement (not just a query) executes before timing out. By default there is no timeout.

This has the same effect as using SQLSetStmtOption to set SQL_QUERY_TIMEOUT or setting the TimesTen general connection attribute SqlQueryTimeout.

See "Setting a timeout or threshold for executing SQL statements".

getColumnName()

const char* getColumnName(int cno)

Returns the name of column number cno.

getColumnNullability()

int getColumnNullability(int cno)

Indicates whether column number cno can NULL data. It returns SQL_NO_NULLS, SQL_NULLABLE, or SQLNULLABLE_UNKNOWN.

getColumnPrecision()

int getColumnPrecision(int cno)

Returns the precision of data in column number cno, referring to the size of the column in the database. For example, for a VARCHAR2(25) column, the precision returned would be 25.

This value is generally interesting only when generating output from table columns of type CHAR, VARCHAR2, NCHAR, NVARCHAR2, BINARY, and VARBINARY.

getColumnScale()

int getColumnScale(int cno)

Returns the scale of data in column number cno, referring to the maximum number of digits to the right of the decimal point.

getColumnType()

int getColumnType(int cno)

Returns the data type of column number cno. The value returned is the ODBC type of the parameter (for example, SQL_INTEGER, SQL_REAL, SQL_BINARY, SQL_CHAR) as found in sql.h. Additional TimesTen ODBC types (SQL_WCHAR, SQL_WVARCHAR) can be found in the TimesTen header file timesten.h.

getNColumns()

int getNColumns()

Returns the number of output columns.

getNParameters()

int getNParameters()

Returns the number of input parameters for the SQL statement.

getParamNullability()

int getParamNullability(int pno)

Indicates whether parameter number pno can have the value NULL. It returns SQL_NO_NULLS, SQL_NULLABLE, or SQLNULLABLE_UNKNOWN.

getParamPrecision()

int getParamPrecision(int pno)

Returns the precision of parameter number pno, referring to the maximum number of digits that are used by the data type. Also see information for getColumnPrecision(), above.

getParamScale()

int getParamScale(int pno)

Returns the scale of parameter number pno, referring to the maximum number of digits to the right of the decimal point.

getParamType()

int getParamType(int pno)

Returns the data type of parameter number pno. The value returned is the ODBC type (for example, SQL_INTEGER, SQL_REAL, SQL_BINARY, SQL_CHAR) as found in sql.h. Additional TimesTen types (SQL_WCHAR, SQL_WVARCHAR) can be found in the TimesTen header file timesten.h.

isBeingExecuted

bool isBeingExecuted()

Indicates whether the statement represented by the TTCmd object is being executed.

batchSize()

u_short batchSize()

Returns the number of statements in the batch.

BindParameter()

void BindParameter(int pno, unsigned short batSz, TYPE* valueP)
void BindParameter(int pno, unsigned short batSz, TYPE* valueP, size_t maxByteLen)
void BindParameter(int pno, unsigned short batSz, TYPE* valueP, 
                   SQLLEN* userByteLenP, size_t maxByteLen)

The overloaded BindParameter() method is used to bind an array of values for a specified parameter in a SQL statement compiled using PrepareBatch(). This allows iterating through a batch of repeated executions of the statement with different values. The pno parameter indicates the position in the statement of the parameter to be bound, starting from the left, where the first parameter is 1, the next is 2, and so on.

See "Binding duplicate parameters" regarding duplicate parameters and the difference between TimesTen mode and Oracle mode in handling them.

The batSz (batch size) value of this call must match the batSz value specified in PrepareBatch(), and the bound arrays should contain at least the batSz number of values. You must determine the correct data type for each parameter. If an invalid parameter number is specified, the specified batch size is a mismatch, or the data buffer is null, then a TTStatus object is thrown as an exception and a runtime error is written to the TTClasses global logging facility at the TTLog::TTLOG_ERR logging level.

Table 3-4 below shows the supported SQL data types and the appropriate versions of BindParameter() to use for each parameter type.

Before each invocation of ExecuteBatch(), the application should fill the bound arrays with valid parameter values. Note that you can use the setParamNull() method to set null values, as described in "setParamNull()". (Be aware that for batch mode, you must use the two-parameter version of setParamNull() that specifies rowno. The one-parameter version is for non-batch use only.)

For the SQL types TT_CHAR, CHAR, TT_VARCHAR, and VARCHAR2, an additional maximum length parameter is required in the BindParameter() call:

• maxByteLen of type size_t is for the maximum length, in bytes, of any value for this parameter position.

For the SQL types TT_NCHAR, NCHAR, TT_NVARCHAR, NVARCHAR2, BINARY, and VARBINARY, two additional parameters are required in the BindParameter() call, an array of parameter lengths and a maximum length:

• userByteLenP is an array of SQLLEN parameter lengths, in bytes, to specify the length of each value in the batch for this parameter position in the SQL statement. This array must be at least batSz in length and filled with valid length values before ExecuteBatch() is called. (You can store SQL_NULL_DATA in the array of parameter lengths for a null value, which is equivalent to using the setParamNull() batch method.)

• maxByteLen is as described above. This indicates the maximum length value that can be specified in any element of the userByteLenP array.

For data types where userByteLenP is not available (or as an alternative where it is available), you can optionally use the setParamLength() batch method to set data lengths, as described in "setParamLength()", and use the setParamNull() batch method to set null values, as described in "setParamNull()".

See Example 3-5 in "ExecuteBatch()" below for examples of BindParameter() usage.

BindParameter(pno, batSz, SQLTINYINT* user_tiP)

BindParameter(pno, batSz, SQLSMALLINT* user_siP)

BindParameter(pno, batSz, SQLINTEGER* user_iP)

BindParameter(pno, batSz, SQLBIGINT* user_biP)

BindParameter(pno, batSz, float* user_fP)

BindParameter(pno, batSz, double* user_dP)

BindParameter(pno, batSz, char** user_cPP, maxByteLen)

BindParameter(pno, batSz, char** user_cPP, maxByteLen)

BindParameter(pno, batSz, SQLWCHAR** user_wcPP, userByteLenP,
              maxByteLen)

BindParameter(pno, batSz, const void** user_binPP, userByteLenP,
              maxByteLen)

BindParameter(pno, batSz, TIMESTAMP_STRUCT* user_tssP)

BindParameter(pno, batSz, DATE_STRUCT* user_dsP)

BindParameter(pno, batSz, TIME_STRUCT* user_tsP)

ExecuteBatch()

int ExecuteBatch(unsigned short numRows)

After preparing a SQL statement with PrepareBatch() and calling BindParameter() for each parameter in the SQL statement, use ExecuteBatch() to execute the statement numRows times. The value of numRows must be no more than the batSz (batch size) value specified in the PrepareBatch() and BindParameter() calls, but can be less than batSz as required by application logic.

This method returns the number of rows that were updated, with possible values in the range 0 to batSz, inclusive. (For those familiar with ODBC, this is the third parameter, *pirow, of an ODBC SQLParamOptions call. Refer to ODBC API reference documentation for information about SQLParamOptions.)

Before calling ExecuteBatch(), the application should fill the arrays of parameters previously bound by BindParameter() with valid values.

A TTStatus object is thrown as an exception if an error occurs (often due to violation of a uniqueness constraint). In this event, the return value is not valid and the batch is incomplete and should generally be rolled back.

Example 3-5 shows how to use the ExecuteBatch() method. The bulktest Quick Start demo also shows usage of this method. (See "About the TimesTen TTClasses demos".)

CREATE TABLE batch_table (a TT_INTEGER, b VARCHAR2(100));

#define BATCH_SIZE 50
#define VARCHAR_SIZE 100
 
int int_array[BATCH_SIZE];
char char_array[BATCH_SIZE][VARCHAR_SIZE];
 
// Prepare the statement
 
TTCmd insert;
TTConnection connection;
 
// (assume a connection has been established)
 
try {
 
  insert.PrepareBatch (&connection,
                       (const char*)"insert into batch_table values (?,?)",
                       BATCH_SIZE);
 
  // Commit the prepared statement
  connection.Commit();
 
  // Bind the arrays of parameters
  insert.BindParameter(1, BATCH_SIZE, int_array);
  insert.BindParameter(2, BATCH_SIZE, (char **)char_array, VARCHAR_SIZE);
 
  // Execute 5 batches, inserting a total of 5 * BATCH_SIZE rows into
  // the database
  for (int iter = 0; iter < 5; iter++)
  {
    // Populate the value arrays with values.
    // (A more meaningful way of putting data into
    // the database is to read values from a file, for example,
    // rather than generating them arbitrarily.)
 
    for (int i = 0; i < BATCH_SIZE; i++)
    {
      int_array[i] = i * iter + i;
      sprintf(char_array[i], "varchar value # %d", i*iter+ i);
    }
 
    // Execute the batch insert statement,
    // which inserts the entire contents of the
    // integer and char arrays in one operation.
    int num_ins = insert.ExecuteBatch(BATCH_SIZE);
 
    cerr << "Inserted " << num_ins << " rows." << endl;
 
    connection.Commit();
 
  } // for iter
 
} catch (TTError er1) {
  cerr << er1 << endl;
}

TimesTen has features to control database access with object-level resolution for database objects such as tables, views, materialized views, sequences, and synonyms. Access control privileges are checked both when SQL is prepared and when it is executed in the database, with most of the performance cost coming at prepare time. See "Considering TimesTen features for access control".

for (int iter = 0; iter < 5; iter++)
{

  // Populate the value arrays with values.
  // (A better way of putting meaningful data into
  // the database is to read values from a file,
  // rather than generating them arbitrarily.)

  for (int i = 0; i < BATCH_SIZE; i++)
  {
    int_array[i] = i * iter + i;
    sprintf(char_array[i], "varchar value # %d", i*iter+i);
  }

  // now we execute the batch insert statement,
  // which does the work of inserting the entire
  // contents of the integer and char arrays in
  // one operation

  int num_ins = insert.ExecuteBatch(BATCH_SIZE);

  cerr << "Inserted " << num_ins << " rows (expected "
       << BATCH_SIZE << " rows)." << endl;

  if (num_ins == BATCH_SIZE) {
    cerr << "Committing batch" << endl;
    connection.Commit();
  }
  else {
    cerr << "Some rows were not inserted as expected, rolling back "
         << "transaction." << endl;
    connection.Rollback();
    break; // jump out of batch insert loop
  }

} // for loop

PrepareBatch()

void PrepareBatch(TTConnection* cP, const char* sqlp, unsigned short batSz)

PrepareBatch() is comparable to the Prepare() method but for batch INSERT, UPDATE, or DELETE statements. The cP and sqlp parameters are used as with Prepare(). See "Prepare()".

The batSz (batch size) parameter specifies the maximum number of insert, update, or delete operations that are performed using subsequent calls to ExecuteBatch().

A TTStatus object is thrown as an exception if an error occurs.

TimesTen has features to control database access with object-level resolution for database objects such as tables, views, materialized views, sequences, and synonyms. Access control privileges are checked both when SQL is prepared and when it is executed in the database, with most of the performance cost coming at prepare time. See "Considering TimesTen features for access control".

setParamLength()

(Version for batch operations)

void setParamLength(int pno, unsigned short rowno, int byteLen)

This method sets the length of a bound parameter value before a call to ExecuteBatch(). The pno argument specifies the parameter number in the SQL statement (where the first parameter is number 1). The rowno argument specifies the row number in the array of parameters being bound (where the first row is row number 1). The byteLen parameter specifies the desired length, in bytes, not counting the NULL terminator. Alternatively, byteLen can be set to SQL_NTS for a null-terminated string. (It can also be set to SQL_NULL_DATA, which is equivalent to using the setParamNull() batch method, described next.)

setParamNull()

(Version for batch operations)

void setParamNull(int pno, unsigned short rowno)

This method sets a bound parameter value to NULL before a call to ExecuteBatch(). The pno argument specifies the parameter number in the SQL statement (where the first parameter is number 1). The rowno argument specifies the row number in the array of parameters being bound (where the first row is row number 1).

fetchCatalogData()

void fetchCatalogData()

This is the only TTCatalog method that interacts with the database. It reads the catalogs in the database for information about tables and indexes, storing the information into TTCatalog internal data structures.

Subsequent use of the constructed TTCatalog object is completely offline after it is constructed. It is no longer connected to the database.

You must call this method before you use any of the TTCatalog accessor methods.

This example demonstrates the use of TTCatalog.

TTConnection conn;
conn.Connect(DSN=TptbmData37);
TTCatalog cat (&conn);
cat.fetchCatalogData(); 
// TTCatalog cat is no longer connected to the database;
// you can now query it through its read-only methods.
cerr << "There are " << cat.getNumTables() << " tables in this database:" << endl;
for (int i=0; i < cat.getNumTables(); i++)
cerr << cat.getTable(i).getTableOwner() << "." 
     << cat.getTable(i).getTableName() << endl;

getNumSysTables()

int getNumSysTables()

Returns the number of system tables in the database. Also see getNumTables() and getNumUserTables().

getNumTables()

int getNumTables() 

Returns the total number of tables in the database (user plus system tables). Also see getNumSysTables() and getNumUserTables().

getNumUserTables()

int getNumUserTables() 

Returns the number of user tables in the database. Also see getNumSysTables() and getNumTables().

getTable()

const TTCatalogTable& getTable(const char* owner, const char* tblname)
const TTCatalogTable& getTable(int tno) 

Returns a constant reference to the TTCatalogTable object for the specified table. Also see getUserTable().

For the first signature, this is for the table named tblname and owned by owner.

For the second signature, this is for the table corresponding to table number tno in the system. This is intended to facilitate iteration through all the tables in the system. The order of the tables in this array is arbitrary.

The following relationship is true:

0 <= tno < getNumTables()

Also see "TTCatalogTable".

getTableIndex()

int getTableIndex(const char* owner, const char* tblname) const

This method fetches the index in the TTCatalog object for the specified owner.tblname object. It returns -2 if owner.tblname does not exist. It returns -1 if fetchCatalogData() was not called first.

Example 3-8 retrieves information about the TTUSER.MYDATA table from a TTCatalog object. You can then call methods of TTCatalogTable, described next, to get information about this table.

TTConnection conn;
conn.Connect(...);
TTCatalog cat (&conn);
cat.fetchCatalogData();

int idx = cat.getTableIndex("TTUSER", "MYDATA");
if (idx < 0) {
  cerr << "Table TTUSER.MYDATA does not exist." << endl;
  return;
}
 
TTCatalogTable &table = cat.getTable(idx);

getUserTable()

const TTCatalogTable& getUserTable(int tno)

Returns a constant reference to the TTCatalogTable object corresponding to user table number tno in the system. This method is intended to facilitate iteration through all of the user tables in the system. The order of the user tables in this array is arbitrary. Also see getTable().

The following relationship is true:

0 <= tno < getNumUserTables()

getColumn()

const TTCatalogColumn& getColumn(int cno)

Returns a constant reference to the TTCatalogColumn object corresponding to column number cno in the table. This method is intended to facilitate iteration through all the columns in the table.

The following relationship is true:

0 <= cno < getNumColumns()

getIndex()

const TTCatalogIndex& getIndex(int num)

Returns a constant reference to the TTCatalogIndex object corresponding to index number num in the table. This method is intended to facilitate iteration through all the indexes of the table. The order of the indexes of a table in this array is arbitrary.

The following relationship is true:

0 <= num < getNumIndexes()

getNumColumns()

int getNumColumns()

Returns the number of columns in the table.

getNumIndexes()

int getNumIndexes()

Returns the number of indexes on the table.

getNumSpecialColumns()

int getNumSpecialColumns()

Returns the number of special columns in this TTCatalogTable object. Because TimesTen supports only rowid special columns, this always returns 1.

Also see "TTCatalogSpecialColumn".

getSpecialColumn()

const TTCatalogSpecialColumn& getSpecialColumn(int num) const

Returns a special column (TTCatalogSpecialColumn object) from this TTCatalogTable object, according to the specified column number. In TimesTen this can be only a rowid pseudocolumn.

Also see "TTCatalogSpecialColumn".

getTableName()

const char* getTableName()

Returns the name of the table.

getTableOwner()

const char* getTableOwner()

Returns the owner of the table.

getTableType()

const char* getTableType() const

Returns the table type of this TTCatalogTable object, as from an ODBC SQLTables call. In TimesTen this may be TABLE, SYSTEM TABLE, VIEW, or SYNONYM.

isSystemTable()

bool isSystemTable()

Returns TRUE if the table is a system table (owned by SYS, TTREP, or GRID), or FALSE otherwise.

The isSystemTable() method and isUserTable() method (described next) are useful for applications that iterate over all tables in a database after a call to TTCatalog::fetchCatalogData(), so that you can filter or annotate tables to differentiate the system and user tables. The TTClasses demo program catalog provides an example of how this can be done. (See "About the TimesTen TTClasses demos".)

isUserTable()

bool isUserTable()

Returns TRUE if this is a user table, which is to say it is not a system table, or FALSE otherwise. Note that isUserTable() returns the opposite of isSystemTable() for any table. The description of isSystemTable() discusses the usage and usefulness of these methods.

getColumnName()

const char* getColumnName()

Returns the name of the column.

getDataType()

int getDataType()

Returns an integer representing the data type of the column. This is the standard ODBC SQL type code or a TimesTen extension type code.

getLength()

int getLength()

Returns the length of data in the column, in bytes.

getNullable()

int getNullable()

Indicates whether the column can contain NULL values. It returns SQL_NO_NULLS, SQL_NULLABLE, or SQL_NULLABLE_UNKNOWN.

getPrecision()

int getPrecision()

Returns the precision of data in the column, referring to the maximum number of digits that are used by the data type.

getRadix()

int getRadix()

Returns the radix of the column, according to ODBC SQLColumns function output.

getScale()

int getScale()

Returns the scale of data in the column, which is the maximum number of digits to the right of the decimal point.

getTypeName()

const char* getTypeName()

Returns the TimesTen name of the type returned by getDataType().

getCollation()

char getCollation (int num)

Returns the collation of column number num in the index. Values returned are "A" for ascending order or "D" for descending order.

getColumnName()

const char* getColumnName(int num)

Returns the name of column number num in the index.

getIndexName()

const char* getIndexName()

Returns the name of the index.

getIndexOwner()

const char* getIndexOwner()

Returns the owner of the index.

getNumColumns()

int getNumColumns()

Returns the number of columns in the index.

getTableName()

const char* getTableName()

Returns the name of the table for which the index was created. This is the table represented by the TTCatalogTable object from which the index was retrieved through a TTCatalogTable::getIndex() call.

getType()

int getType()

Returns the type of the index. For TimesTen, the allowable values are PRIMARY_KEY, HASH_INDEX (the same as PRIMARY_KEY), and RANGE_INDEX.

isUnique()

bool isUnique()

Returns TRUE if the index is a unique index, or FALSE otherwise.

getColumnName()

const char* getColumnName()

Returns the name of the special column.

getDataType()

int getDataType()

Returns an integer representing the ODBC SQL data type of the special column. In TimesTen this can be only SQL_ROWID.

getLength()

int getLength()

Returns the length of data in the special column, in bytes.

getPrecision()

int getPrecision()

Returns the precision for data in the special column, referring to the maximum number of digits used by the data type.

getScale()

int getScale()

Returns the scale for data in the special column, referring to the maximum number of digits to the right of the decimal point.

getTypeName()

const char* getTypeName()

Returns the data type name that corresponds to the ODBC SQL data type value returned by getDataType(). In TimesTen this can be only ROWID.

ackUpdates()

void ackUpdates()

Use this method to advance the bookmark to the next set of updates. After you have acknowledged a set of updates, the updates cannot be viewed again by this bookmark. Therefore, a setBookmarkIndex() call does not allow you to replay XLA records that have been acknowledged by a call to ackUpdates(). (See the descriptions of getBookmarkIndex() and setBookmarkIndex() for information about replaying a set of updates.)

Applications should acknowledge updates when a batch of XLA records have been read and processed, so that the transaction log does not fill up available disk space; however, do not call ackUpdates() too frequently, because it is a relatively expensive operation.

If an application uses XLA to read a batch of records and then a failure occurs before ackUpdates() is called, the records are retrieved when the application reestablishes its XLA connection.

Connect()

virtual void Connect(const char* connStr, const char* bookmarkStr, 
                     bool createBookmarkFlag)
virtual void Connect(const char* connStr, const char* username, 
                     const char* password, const char* bookmarkStr, 
                     bool createBookmarkFlag)
virtual void Connect(const char* connStr, 
                     TTConnection::DRIVER_COMPLETION_ENUM driverCompletion,
                     const char* bookmarkStr, bool createBookmarkFlag)

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

Each XLA connection has a bookmark name associated with it, so that after disconnecting and reconnecting, the same place in the transaction log can be found. The name for the bookmark of a connection is specified in the bookmarkStr parameter.

For the first set of methods listed above, the createBookmarkFlag boolean parameter indicates whether the specified bookmark is new or was previously created. If you indicate that a bookmark is new (createBookmarkFlag==true) and it already exists, an error is returned. Similarly, if you indicate that a bookmark already exists (createBookmarkFlag==false) and it does not exist, an error is returned.

For the second set of methods listed, without createBookmarkFlag, TTClasses first tries to connect reusing the supplied bookmark (behavior equivalent to createBookmarkFlag==false). If that bookmark does not exist, TTClasses then tries to connect and create a new bookmark with the name bookmarkStr (behavior equivalent to createBookmarkFlag==true). These methods are provided as a convenience, to simplify XLA connection logic if you would rather not concern yourself with whether the XLA bookmark exists.

In either mode, with or without createBookmarkFlag, specify a user name and password either through the connection string or through the separate parameters, or specify a DRIVER_COMPLETION_ENUM value. Refer to "TTConnection" for information about DRIVER_COMPLETION_ENUM.

Privilege to connect to a database must be granted to users through the CREATE SESSION privilege, either directly or through the PUBLIC role. See "Access control for connections". In addition, the XLA privilege is required to create an XLA connection.

deleteBookmarkAndDisconnect()

void deleteBookmarkAndDisconnect()

This method first deletes the bookmark that is currently associated with the connection, so that the database no longer keeps records relevant to that bookmark, then disconnects from the database.

To disconnect without deleting the bookmark, use the Disconnect() method instead.

Disconnect()

virtual void Disconnect()

This method closes an XLA connection to a database. The XLA bookmark persists after you call this method.

To delete the bookmark and disconnect from the database, use deleteBookmarkAndDisconnect() instead.

fetchUpdatesWait()

void fetchUpdatesWait(ttXlaUpdateDesc_t*** arry, int maxrecs,
                      int* recsP, int seconds)

Use this method to fetch a set of records describing changes to a database. A list of ttXlaUpdateDesc_t structures is returned. If there are no XLA updates to be fetched, this method waits the specified number of seconds before returning.

Specify the number of seconds to wait, seconds, and the maximum number of records to receive, maxrecs. The method returns the number of records actually received, recsP, and an array of pointers, arry, that point to structures defining the changes.

The ttXlaUpdateDesc_t structures that are returned by this method are defined in the XLA specification. No C++ object-oriented encapsulation of these methods is provided. Typically, after calling fetchUpdatesWait(), an application processes these ttXlaUpdateDesc_t structures in a sequence of calls to TTXlaTableList::HandleChange().

See "ttXlaUpdateDesc_t" in Oracle TimesTen In-Memory Database C Developer's Guide for information about that data structure.

getBookmarkIndex()

void getBookmarkIndex()

This method gets the current bookmark location, storing it into a class private data member where it is available for use by subsequent setBookmarkIndex() calls.

setBookmarkIndex()

void setBookmarkIndex()

This method returns to the saved transaction log index, restoring the bookmark to the address previously acquired by a getBookmarkIndex() call. Use this method to replay a batch of XLA records.

Note that ackUpdates() invalidates the stored transaction log placeholder. After ackUpdates(), a call to setBookmarkIndex() returns an error because it is no longer possible to go back to the previously acquired bookmark location.

columnPrec()

int columnPrec(int cno)

Returns the precision of data in column number cno of the row image, referring to the maximum number of digits that are used by the data type.

columnScale()

int columnScale(int cno)

Returns the scale of data in column number cno of the row image, referring to the maximum number of digits to the right of the decimal point.

Get()

void Get(int cno, TYPE* valueP)
void Get(int cno, TYPE* valueP, int* byteLenP)

Fetches the value of column number cno in the row image. These methods are very similar to the TTCmd::getColumn() methods.

Table 3-5 that follows shows the supported SQL data types and the appropriate versions of Get() to use for each data type. Design the application according to the types of data that are stored. For example, data of type NUMBER(9,0) can be accessed by the Get(int, int*) method without loss of information.

Get(cno, char** cPP)

Get(cno, SQLWCHAR** wcPP, byteLenP)

Get(cno, char** cPP)

Get(cno, SQLWCHAR** wcPP, byteLenP)

Get(cno, SQLTINYINT* iP)

Get(cno, short* iP)

Get(cno, int* iP)

Get(cno, SQLBIGINT* biP)

Get(cno, float* fP)

Get(cno, double* dP)

Get(cno, char** cPP)

Get(cno, TIME_STRUCT* tP)

Get(cno, DATE_STRUCT* dP)

Get(cno, TIMESTAMP_STRUCT* tsP)

Get(cno, const void** binPP,
    byteLenP)

Get(cno, const void** binPP,
    byteLenP)

Get(cno, double* dP)

Get(cno, char** cPP)

Get(cno, short* iP)

Get(cno, int* iP)

Get(cno, SQLBIGINT* biP)

Get(cno, TIMESTAMP_STRUCT* tsP)

Get(cno, TIMESTAMP_STRUCT* tsP)

Get(cno, char** cPP)

Get(cno, SQLWCHAR** wcPP, byteLenP)

Get(cno, char** cPP)

Get(cno, SQLWCHAR** wcPP, byteLenP)

Get(cno, double* dP)

Get(cno, char** cPP)

Get(cno, const void** binPP,
    byteLenP)

Get(cno, char** cPP)

Get(cno, SQLWCHAR** wcPP, byteLenP)

getColumn()

const TTXlaColumn* getColumn(u_int cno) const

Returns a TTXlaColumn object with metadata for column number cno in the row image.

isColumnTTTimestamp()

bool isColumnTTTimestamp(int cno)

Returns TRUE if column number cno in the row image is a TT_TIMESTAMP column, or FALSE otherwise.

isNull()

bool isNull(int cno)

Indicates whether the column number cno in the row image has the value NULL, returning TRUE if so or FALSE if not.

numUpdatedCols()

SQLUSMALLINT numUpdatedCols()

Returns the number of columns that have been updated in the row image.

setTuple()

void setTuple(ttXlaUpdateDesc_t* updateDescP, int whichTuple)

Before a row can be examined, this method must be called to associate the TTXlaRowViewer object with a particular row image. It is invoked inside the TTXlaTableHandler::HandleInsert(), HandleUpdate(), or HandleDelete() method, or by a user-written overloaded method. You would typically call it when overloading the TTXlaTableHandler::HandleChange() method. The Quick Start xlasubscriber1 demo provides an example of its usage. (See "About the TimesTen TTClasses demos".)

The ttXlaUpdateDesc_t structures that are returned by TTXlaPersistConnection::fetchUpdatesWait() contain either zero, one, or two rows. Note the following:

• Structures that define a row that was inserted into a table contain the row image of the inserted row.

• Structures that define a row that was deleted from a table contain the row image of the deleted row.

• Structures that define a row that was updated in a table contain the images of the row before and after the update.

• Structures that define other changes to the table or the database contain no row images. For example, structures reporting that an index was dropped contain no row images.

The setTuple() method takes two arguments:

• A pointer to a particular ttXlaUpdateDesc_t structure defining a database change

• An integer specifying which type of row image in the update structure should be examined

  The following are valid values:

  • INSERTED_TUP: Examine the inserted row.

  • DELETED_TUP: Examine the deleted row.

  • UPDATE_OLD_TUP: Examine the row before it was updated.

  • UPDATE_NEW_TUP: Examine the row after it was updated.

updatedCol()

SQLUSMALLINT updatedCol(u_int cno)

Returns the column number of a column that has been updated. For the input parameter you can iterate from 1 through n, where n is the number returned by numUpdatedCols(). Example 3-9 shows a snippet from the TimesTen Quick Start demo xlasubscriber1, where updatedCol() is used with numUpdatedCols() to retrieve each column that has been updated. (See "About the TimesTen TTClasses demos".)

void
SampleHandler::HandleUpdate(ttXlaUpdateDesc_t* )
{
  cerr << row2.numUpdatedCols() << " column(s) updated: ";
  for ( int i = 1; i <= row2.numUpdatedCols(); i++ )
  {
    cerr << row2.updatedCol(i) << "("
         << row2.getColumn(row2.updatedCol(i)-1)->getColName() << ") ";
  }
  cerr << endl;
}

DisableTracking()

virtual void DisableTracking()

Disables XLA update tracking for the table. After this method is called, the XLA bookmark no longer captures information about changes to the table.

EnableTracking()

virtual void EnableTracking()

Enables XLA update tracking for the table. Until this method is called, the XLA bookmark does not capture information about changes to the table.

generateSQL()

void generateSQL (ttXlaUpdateDesc_t* updateDescP, char* buffer, 
                  SQLINTEGER maxByteLen, SQLINTEGER* actualByteLenP)

This method prints the SQL associated with a given XLA record. The SQL string is returned through the buffer parameter. Allocate space for the buffer and specify its maximum length, maxByteLen. The actualByteLenP parameter returns information about the actual length of the SQL string returned.

If maxByteLen is less than the length of the generated SQL string, a TTStatus error is thrown and the contents of buffer and actualByteLenP are not modified.

HandleChange()

virtual void HandleChange(ttXlaUpdateDesc_t* updateDescP)
virtual void HandleChange(ttXlaUpdateDesc_t* updateDescP, void* pData)

Dispatches a ttXlaUpdateDesc_t object to the appropriate handling routine for processing. The update description is analyzed to determine if it is for a delete, insert or update operation. The appropriate handing method is then called: HandleDelete(), HandleInsert(), or HandleUpdate().

Classes that inherit from TTXlaTableHandler can use the optional pData parameter when they overload the TTXlaTableHandler::HandleChange() method. This optional parameter is useful for determining whether the batch of XLA records that was just processed ends on a transaction boundary. Knowing this helps an application decide the appropriate time to invoke TTConnection::ackUpdates(). See "Acknowledging XLA updates at transaction boundaries" for an example that uses the pData parameter.

Also see "HandleChange()" for TTXlaTableList objects.

HandleDelete()

virtual void HandleDelete(ttXlaUpdateDesc_t* updateDescP) = 0

This method is invoked whenever the HandleChange() method is called to process a delete operation.

HandleDelete() is not implemented in the TTXlaTableHandler base class. It must be implemented by any classes derived from it, with appropriate logic to handle deleted rows.

The row that was deleted from the table is available through the protected member row of type TTXlaRowViewer.

HandleInsert()

virtual void HandleInsert(ttXlaUpdateDesc_t* updateDescP) = 0

This method is invoked whenever the HandleChange() method is called to process an insert operation.

HandleInsert() is not implemented in the TTXlaTableHandler base class. It must be implemented by any classes derived from it, with appropriate logic to handle inserted rows.

The row that was inserted into the table is available through the protected member row of type TTXlaRowViewer.

HandleUpdate()

virtual void HandleUpdate(ttXlaUpdateDesc_t* updateDescP) = 0

This method is invoked whenever the HandleChange() method is called to process an update operation.

HandleUpdate() is not implemented in the TTXlaTableHandler base class. It must be implemented by any classes derived from it, with appropriate logic to handle updated rows.

The previous version of the row that was updated from the table is available through the protected member row of type TTXlaRowViewer. The new version of the row is available through the protected member row2, also of type TTXlaRowViewer.

add()

void add(TTXlaTableHandler* tblh)

Adds a TTXlaTableHandler object to the list.

del()

void del(TTXlaTableHandler* tblh)

Deletes a TTXlaTableHandler object from the list.

HandleChange()

void HandleChange(ttXlaUpdateDesc_t* updateDescP)
void HandleChange(ttXlaUpdateDesc_t* updateDescP, void* pData)

When a ttXlaUpdateDesc_t object is received from XLA, it can be processed by calling this method, which determines which table the record references and calls the HandleChange() method of the appropriate TTXlaTableHandler object.

See "HandleChange()" for TTXlaTableHandler objects, including a discussion of the pData parameter.

getColNumber()

int getColNumber(const char* colNameP) const

For a specified column name in the table, this method returns its column number, or -1 if there is no column by that name.

getNCols()

int getNCols() const

Returns the number of columns in the table.

getOwnerName()

const char* getOwnerName() const

Returns the user name of the owner of the table.

getTableName()

const char* getTableName() const

Returns the name of the table.

getColName()

const char* getColName() const

Returns the name of the column.

getPrecision()

SQLULEN getPrecision() const

Returns the precision for data in the column, referring to the maximum number of digits that are used by the data type.

getScale()

int getScale() const

Returns the scale for data in the column, referring to the maximum number of digits to the right of the decimal point.

getSize()

SQLUINTEGER getSize() const

Returns the size of values in the column, in bytes.

getSysColNum()

SQLUINTEGER getSysColNum() const

This is the system-generated column number of the column, numbered from 1. It equals the corresponding COLNUM value in SYS.COLUMNS. (See "SYS.COLUMNS" in Oracle TimesTen In-Memory Database System Tables and Views Reference.)

getType()

int getType() const

Returns an integer representing the TimesTen XLA data type (TTXLA_xxx) of the column. This is a value from the dataType field of the TimesTen ttXlaColDesc_t data structure. In some cases this corresponds to an ODBC SQL data type (SQL_xxx) and the corresponding standard integer value.

Refer to "About XLA data types" in Oracle TimesTen In-Memory Database C Developer's Guide for information regarding TimesTen XLA data types. The corresponding integer values are defined for use in any TTClasses application that includes the TTXla.h header file.

Also refer to "ttXlaColDesc_t" in Oracle TimesTen In-Memory Database C Developer's Guide for information about that data structure.

getUserColNum()

SQLUINTEGER getUserColNum() const

Returns a column number optionally specified by the user through the ttSetUserColumnID TimesTen built-in procedure, or 0.

See "ttSetUserColumnID" in Oracle TimesTen In-Memory Database Reference.

isNullable()

bool isNullable() const

Returns TRUE if null values are allowed in the column, or FALSE otherwise.

isPKColumn()

bool isPKColumn() const

Returns TRUE if this column is the primary key for the table, or FALSE otherwise.

isTTTimestamp()

bool isTTTimestamp() const

Returns TRUE if this column is a TT_TIMESTAMP column, or FALSE otherwise.

isUpdated()

bool isUpdated() const

Returns TRUE if this column was updated, or FALSE otherwise.