Skip Headers
Oracle® TimesTen In-Memory Database C Developer's Guide
Release 11.2.1

Part Number E13066-02
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
View PDF

9 XLA Reference

This chapter provides reference information for the Transaction Log API (XLA) described in "XLA and TimesTen Event Management". It includes the following topics:

About XLA functions

This section includes general information about XLA functions.

About return codes

All of the XLA API functions described in this chapter return a value of type SQLRETURN, which is defined by ODBC to have one of the following values:

  • SQL_SUCCESS

  • SQL_SUCCESS_WITH_INFO

  • SQL_NO_DATA_FOUND

  • SQL_ERROR

See "Handling XLA errors" for information on handling XLA errors.

About parameter types (input, output, input-output)

In the function descriptions:

  • All parameters are input-only unless otherwise indicated.

  • Output parameters are prefixed with OUT.

  • Input-output parameters are prefixed with IN OUT.

About results output by functions

Most routines in this API copy results to application buffers. Those few routines that produce pointers to buffers containing results are guaranteed to remain valid only until the next call with the same XLA handle.

Exceptions to this rule include the following.

  • Buffers remain valid across calls to the ttXlaError function that supplies diagnostic information.

  • Results returned by ttXlaNextUpdate remain valid until the next call to ttXlaNextUpdate.

    ttXlaConfigBuffer, or ttXlaAcknowledge (in persistent mode). If the application must retain access to the buffers for a longer time, the application must copy the information from the buffer returned by XLA to an application-owned buffer.

Character string values in XLA are null- terminated, except for actual column values. Fixed-length CHAR columns are space-padded to their full length. VARCHAR columns have an explicit length encoded.

XLA uses the same data structures for both 32- and 64-bit platforms. The types SQLUINTEGER and SQLUBIGINT are used to refer to 32- and 64-bit integers unambiguously. Issues of alignment and padding are addressed by filling the type definition so that each SQLUINTEGER value is on a 4-byte boundary and each SQLUBIGINT value is on an 8-byte boundary. For a description of storage requirements for other TimesTen data types, see "Understanding rows" in Oracle TimesTen In-Memory Database Operations Guide.

About required privileges

"Access control impact on XLA" introduces the effects of TimesTen access control features on XLA functionality. Any XLA functionality requires the system privilege XLA.

Summary of XLA functions by category

As described in Chapter 5, "XLA and TimesTen Event Management", TimesTen XLA can be used to detect updates on a data store or as a toolkit to build your own replication solution. You can initialize XLA in either persistent or non-persistent mode.

This section categorizes the XLA functions based on their use and provides a brief description of each function. It includes the following categories:

XLA core functions including data type conversion functions

The following table lists core XLA functions that can be used by any XLA application:

Function Description
ttXlaClose Closes the XLA handle opened by ttXlaPersistOpen.
ttXlaConvertCharType Converts column data into the connection character set.
ttXlaError Retrieves error information.
ttXlaErrorRestart Resets error stack information.
ttXlaGetColumnInfo Retrieves information about all the columns in the table.
ttXlaGetTableInfo Retrieves information about a table.
ttXlaGetVersion Retrieves the current version of XLA.
ttXlaNextUpdate Retrieves a batch of updates from TimesTen.
ttXlaNextUpdateWait Retrieves a batch of updates from TimesTen. Will wait for a specified time if no updates are available in the transaction log.
ttXlaTableByName Finds the system and user table identifiers for a table given the table's owner and name.
ttXlaTableStatus Sets and retrieves XLA status for a table.
ttXlaSetVersion Sets the XLA version to be used.
ttXlaTableVersionVerify Checks whether the cached table definitions are compatible with the XLA record being processed.
ttXlaVersionColumnInfo Retrieves information about the columns in a table for which a change update record must be processed.
ttXlaVersionCompare Compares two XLA versions.

See "Writing an XLA event-handler application" for a discussion on how to use most of these functions.

The following table lists data type conversion functions that can be used by any XLA application:

Function Description
ttXlaDateToODBCCType Converts a TTXLA_DATE_TT value to an ODBC C value usable by applications.
ttXlaDecimalToCString Converts a TTXLA_DECIMAL_TT value to a character string usable by applications.
ttXlaNumberToBigInt Converts a TTXLA_NUMBER value to a SQLBIGINT C value usable by applications.
ttXlaNumberToCString Converts a TTXLA_NUMBER value to a character string usable by applications.
ttXlaNumberToDouble Converts a TTXLA_NUMBER value to a long floating point number value usable by applications.
ttXlaNumberToInt Converts a TTXLA_NUMBER value to an integer usable by applications.
ttXlaNumberToSmallInt Converts a TTXLA_NUMBER value to a SQLSMALLINT C value usable by applications.
ttXlaNumberToTinyInt Converts a TTXLA_NUMBER value to a SQLCHAR C value usable by applications.
ttXlaNumberToUInt Converts a TTXLA_NUMBER value to an unsigned integer usable by applications.
ttXlaOraDateToODBCTimeStamp Converts a TTXLA_DATE value to an ODBC timestamp usable by applications.
ttXlaOraTimeStampToODBCTimeStamp Converts a TTXLA_TIMESTAMP value to an ODBC timestamp usable by applications.
ttXlaRowidToCString Converts a ROWID value to a character string value usable by applications.
ttXlaTimeToODBCCType Converts a TTXLA_TIME value to an ODBC C value usable by applications.
ttXlaTimeStampToODBCCType Converts a TTXLA_TIMESTAMP_TT value to an ODBC C value usable by applications.

For more information about XLA data types, see "About XLA data types".

XLA persistent mode functions

The following table lists the functions that are exclusive to operating XLA in persistent mode:

Function Description
ttXlaPersistOpen Initializes a handle to a TimesTen data store to access the transaction log in persistent mode.
ttXlaAcknowledge Acknowledges receipt of one or more transaction update records from the transaction log.
ttXlaDeleteBookmark Deletes a transaction log bookmark.
ttXlaGetLSN Retrieves the log record identifier of the current bookmark for a data store.
ttXlaSetLSN Sets the log record identifier of the current bookmark for a data store.

See "Writing an XLA event-handler application" for a discussion on how to use these functions.

XLA non-persistent mode functions

Note:

TimesTen recommends using XLA in persistent mode.

The following table lists the functions that are exclusive to operating XLA in non-persistent mode:

Function Description
ttXlaOpenTimesTen Initializes a handle to a TimesTen data store to access the transaction log in non-persistent mode.
ttXlaConfigBuffer Sets the size of the XLA staging buffer.
ttXlaStatus Retrieves the current XLA status.
ttXlaResetStatus Resets all the XLA statistics counters.

XLA replication functions

The following table lists the functions that are exclusive to using XLA as a replication mechanism include the following.

Function Description
ttXlaApply Applies the update to the data store or database associated with the XLA handle.
ttXlaTableCheck Verifies that the named table in the table description received from the sending data store is compatible with the receiving data store.
ttXlaLookup Looks for an update record for a table with a specific key value.
ttXlaRollback Rolls back a transaction.
ttXlaCommit Commits a transaction.
ttXlaGenerateSQL Generates a SQL statement that expresses the effect of an update record.

See "Using XLA as a replication mechanism" for a discussion on how to use these functions.


XLA function reference

This section provides reference information for each XLA function. Functions are listed in alphabetical order.


ttXlaAcknowledge

Description

This function is used in persistent mode to acknowledge that one or more records have been read from the transaction log by the ttXlaNextUpdate or ttXlaNextUpdateWait function.

After you make this call, the bookmark is reset so that you cannot reread any of the previously returned records. Call ttXlaAcknowledge only when messages have been completely processed.

Notes:

  • The bookmark is only reset for the specified handle. Other handles in the system may still be able to access those earlier transactions.

  • The bookmark is reset even in the absence of any relevant update records to acknowledge.

Note that ttXlaAcknowledge is an expensive operation that should be used only as necessary. Calling ttXlaAcknowledge more than once per reading of the transaction log file does not reduce the volume of the transaction log since XLA only purges transaction logs a file at a time. To detect when a new transaction log file is generated, you can find out which log file a bookmark is in by examining the purgeLSN (represented by the PURGELSNHIGH and PURGELSNLOW values) for the bookmark in the system table SYS.TRANSACTION_LOG_API. You can then call ttXlaAcknowledge to purge the old transaction log files. (Note that you must have ADMIN or SELECT ANY TABLE privilege to view this table.)

The second purpose of ttXlaAcknowledge is to ensure that the XLA application does not see the acknowledged records if it were to connect to a previously used bookmark by calling the ttXlaPersistOpen function with the XLAREUSE option. If you intend to reuse a bookmark, call ttXlaAcknowledge to reset the bookmark position to the current record before calling ttXlaClose.

See "Retrieving update records from the transaction log" for a discussion about using this function.

Required privilege

Requires the system privilege XLA.

Syntax

SQLRETURN ttXlaAcknowledge(ttXlaHandle_h handle)

Parameters

Parameter Type Description
handle ttXlaHandle_h The transaction log handle.

Returns

SQL_SUCCESS if call is successful. Otherwise, use ttXlaError to report the error.

Example

rc = ttXlaAcknowledge(xlahandle);

See also


ttXlaNextUpdate
ttXlaNextUpdateWait

ttXlaApply

Description

Applies an update to the data store or database associated with the handle. The return value indicates whether the update was successful. The return also shows if the update encountered a persistent problem. (To see whether the update encountered a transient problem such as a deadlock or timeout, you must call ttXlaError and check the error code.)

If the ttXlaUpdateDesc_t record is a transaction commit, the underlying data store or database transaction is committed. No other transaction commits are performed by ttXlaApply. If the parameter test is true, the "old values" in the update description are compared against the current contents of the data store for record updates and deletions. If the old value in the update description does not match the corresponding row in the data store, this function rejects the update and returns an sb_ErrXlaTupleMismatch error.

See "Using XLA as a replication mechanism" for a discussion about using this function.

Note:

ttXlaApply cannot be used if the table definition was updated since it was originally written to the transaction log. Unique key and foreign key constraints are checked at the row level rather than at the statement level.

Required privilege

Requires the system privilege ADMIN.

Additional privileges may be required on the target database for the ttXlaApply operation. For example, to apply a CREATETAB (create table) record to the target database, you must have CREATE TABLE or CREATE ANY TABLE privilege, as appropriate.

Syntax

SQLRETURN ttXlaApply(ttXlaHandle_h handle,
                     ttXlaUpdateDesc_t *record,
                     SQLINTEGER test)

Parameters

Parameter Type Description
handle ttXlaHandle_h The transaction log handle for the data store.
record ttXlaUpdateDesc_t * Transaction to generate SQL statement.
test SQLINTEGER Test for old values (0 = test off; 1 = test on).

Returns

SQL_SUCCESS if call is successful. Otherwise, use ttXlaError to report the error.

If test is 1 and ttXlaApply detects an update conflict, an sb_ErrXlaTupleMismatch error is returned.

Example

This example applies an update to a data store without testing for the previous value of the existing record:

ttXlaUpdateDesc_t record;
rc = ttXlaApply(xlahandle, &record, 0);

Note

When calling ttXlaApply, it is possible for the update to timeout or deadlock with concurrent transactions. In such cases, it is the application's responsibility to roll the transaction back and reapply the updates.

See also


ttXlaCommit
ttXlaRollback
ttXlaLookup
ttXlaTableCheck
ttXlaGenerateSQL

ttXlaClose

Description

Closes an XLA handle that was opened by ttXlaPersistOpen. See "Terminating an XLA application" for a discussion about using this function.

Required privilege

Requires the system privilege XLA.

Syntax

SQLRETURN ttXlaClose(ttXlaHandle_h handle)

Parameters

Parameter Type Description
handle ttXlaHandle_h The ODBC handle for the data store.

Returns

SQL_SUCCESS if call is successful. Otherwise, use ttXlaError to report the error.

To close the XLA handle opened in the previous example, use the call:

rc = ttXlaClose(xlahandle);

See also


ttXlaPersistOpen

ttXlaCommit

Description

Commits the current transaction being applied on the handle. This routine commits the transaction regardless of whether the transaction has completed. You can call this routine to respond to transient errors (timeout or deadlock) reported by ttXlaApply. ttXlaApply applies the current transaction if it does not encounter an error.

See "Handling timeout and deadlock errors" for a discussion about using this function.

Required privilege

Requires the system privilege XLA.

Syntax

SQLRETURN ttXlaCommit(ttXlaHandle_h handle)

Parameters

Parameter Type Description
handle ttXlaHandle_h The transaction log handle for the data store.

Returns

SQL_SUCCESS if call is successful. Otherwise, use ttXlaError to report the error.

Example

rc = ttXlaCommit(xlahandle);

See also


ttXlaApply
ttXlaRollback
ttXlaLookup
ttXlaTableCheck
ttXlaGenerateSQL

ttXlaConfigBuffer

Description

This function is valid only when XLA is in non-persistent mode.

You can use the ttXlaConfigBuffer function to both set and get the size of the XLA staging buffer, which is where XLA stages the update records obtained from the transaction log and makes them available to be read by the application.

To first set the size of the staging buffer, specify a value for the newSize parameter and a null value for the oldSize parameter. The new size of the staging buffer is retrieved from *newSize. A size of zero indicates no staging buffer should be allocated.

To change the size of the staging buffer, specify a value for newSize and provide an oldSize parameter. Upon return, *oldSize contains the previous size of the staging buffer, or 0 if the size had not been set.

To retrieve but not change the current size of the staging buffer, specify a null value for the newSize parameter. The current size of the staging buffer is returned in *oldSize.

When choosing the size of your staging buffer, consider that if the buffer is too small, TimesTen updates will exhaust the buffer, causing further updates to be rejected. Conversely, over-allocating space for the buffer wastes memory.

After setting the size of your staging buffer, you can resize it at any time. However, resizing may result in copying the current buffer and therefore incurring substantial performance penalties.

Changes to the staging buffer size are carried out immediately. When the buffer is resized, records that were returned by previous calls to ttXlaNextUpdate or ttXlaNextUpdateWait become invalid.

Only one buffer may be configured for a data store. When the buffer is resized, values returned by previous calls on ttXlaNextUpdate become invalid.

Notes:

  • If the XLA staging buffer is set to a nonzero size and no XLA reader is connected, updates on the data store will be written into the buffer. When the staging buffer becomes full, database operations cannot successfully complete until you either delete the staging buffer (size set to 0) or connect an XLA reader and begin reading from the buffer.

  • If a smaller size is specified for the staging buffer and the current contents will not fit in the smaller size, the buffer size is not changed and an error is returned.

Required privilege

Requires the system privilege XLA.

Syntax

SQLRETURN ttXlaConfigBuffer(ttXlaHandle_h handle,
                            out SQLUBIGINT *oldSize,
                            SQLUBIGINT *newSize)

Parameters

Parameter Type Description
handle ttXlaHandle_h The transaction log handle for the data store.
oldSize out SQLUBIGINT * Current size of the staging buffer.
newSize SQLUBIGINT * New size of the staging buffer.

Returns

SQL_SUCCESS if call is successful. Otherwise, use ttXlaError to report the error.

Example

Assume the following declarations for our examples:

SQLUBIGINT currentSize, requestedSize;

To find the current size of the staging buffer without changing the size:

rc = ttXlaConfigBuffer(xlahandle, &currentSize, NULL);

To set the size of the staging buffer to 400,000 bytes:

requestedSize = 400000;
...
rc = ttXlaConfigBuffer(xlahandle, NULL, &requestedSize);

To change the size of the staging buffer to 400,000 bytes and retrieve the previous size:

requestedSize = 400000;
...
rc = ttXlaConfigBuffer(xla_handle, &currentSize, &requestedSize);

To delete the staging buffer:

requestedSize = 0;
...
rc = ttXlaConfigBuffer(xlahandle, NULL, &requestedSize);

Note

Buffer resizing may copy the current buffer and therefore incur substantial performance penalties. If a smaller size is specified for the staging buffer and the current contents will not fit in the smaller size, the staging buffer size is not changed and an error is returned.

See also


ttXlaOpenTimesTen
ttXlaStatus
ttXlaResetStatus

ttXlaConvertCharType

Description

Converts the column data indicated by colinfo and tup into the connection character set associated with handle and places the result in buf.

Required privilege

Requires the system privilege XLA.

Syntax

SQLRETURN ttXlaConvertCharType (ttXlaHandle_h handle,
                                ttXlaColDesc_t * colinfo,
                                void * tup,
                                void * buf,
                                size_t buflen)

Parameters

Parameter Type Description
handle ttXlaHandle_h The transaction log handle for the data store.
colinfo ttXlaColDesc_t * A pointer to the buffer that holds the column descriptions.
tup void * The data that is to be converted.
buf void * Location where the converted data is placed.
buflen size_t Size of the buffer where the converted data is placed.

Returns

SQL_SUCCESS if call is successful. Otherwise, use ttXlaError to report the error.


ttXlaDateToODBCCType

Description

Converts a TTXLA_DATE_TT value to an ODBC C value usable by applications. See "Converting complex data types" for a discussion about using this function.

Call this function only on a column of data type TTXLA_DATE_TT. The data type can be obtained from the ttXlaColDesc_t structure returned by the ttXlaGetColumnInfo function.

Required privilege

Requires the system privilege XLA.

Syntax

SQLRETURN ttXlaDateToODBCCType(void * fromData,
                               out DATE_STRUCT * returnData)

Parameters

Parameter Type Description
fromData void * Pointer to the date value returned from the transaction log.
returnData out DATE_STRUCT * Pointer to storage allocated to hold the converted date.

Returns

SQL_SUCCESS if call is successful. Otherwise, use ttXlaError to report the error.


ttXlaDecimalToCString

Description

Converts a TTXLA_DECIMAL_TT value to a string usable by applications. The scale and precision values can be obtained from the ttXlaColDesc_t structure returned by the ttXlaGetColumnInfo function. The scale parameter specifies the maximum number of digits after the decimal point. If the decimal value is larger than 1, the precision parameter should specify the maximum number of digits before and after the decimal point. If the decimal value is less than 1, precision is the same as scale.

Call this function only for a column of type TTXLA_DECIMAL_TT. The data type can be obtained from the ttXlaColDesc_t structure returned by the ttXlaGetColumnInfo function.

See "Converting complex data types" for a discussion about using this function.

Required privilege

Requires the system privilege XLA.

Syntax

SQLRETURN ttXlaDecimalToCString(void *fromData,
                                out char *returnData,
                                SQLSMALLINT precision,
                                SQLSMALLINT scale)

Parameters

Parameter Type Description
fromData void * Pointer to the decimal value returned from the transaction log.
returnData out char * Pointer to storage allocated to hold the converted string.
precision SQLSMALLINT If fromData is larger than 1, precision is the maximum number of digits before and after the decimal point. If fromData is less than 1, precision is the same as scale.
scale SQLSMALLINT Maximum number of digits after the decimal point.

Returns

SQL_SUCCESS if call is successful. Otherwise, use ttXlaError to report the error.

Example

This example assumes you have obtained the offset, precision, and scale values from a ttXlaColDesc_t structure and used the offset to obtain a decimal value, pColVal, in a row returned in a transaction log record.

char decimalData[50];
static ttXlaColDesc_t colDesc[255];

rc = ttXlaDecimalToCString(pColVal, (char*)&decimalData,
                                     colDesc->precision, 
                                     colDesc->scale);

ttXlaDeleteBookmark

Description

Deletes the bookmark associated with the specified handle. After the bookmark has been deleted, it is no longer accessible and its identifier may be reused for another bookmark. The deleted bookmark is no longer associated with the data store handle and the effect is the same as having opened the persistent connection with the XLANONE option.

If the bookmark is in use, it cannot be deleted until it is no longer in use.

See "Deleting bookmarks" for a discussion about using this function.

Notes:

  • Do not confuse this with the TimesTen built-in procedure ttXlaBookmarkDelete, documented in "ttXlaBookmarkDelete" in Oracle TimesTen In-Memory Database Reference.

  • You cannot delete replicated bookmarks while the replication agent is running.

Required privilege

Requires the system privilege XLA.

Syntax

SQLRETURN ttXlaDeleteBookmark(ttXlaHandle_h handle)

Parameters

Parameter Type Description
handle ttXlaHandle_h The transaction log handle.

Returns

SQL_SUCCESS if call is successful. Otherwise, use ttXlaError to report the error.

Example

Delete the bookmark for xlahandle:

rc = ttXlaDeleteBookmark(xlahandle);

See also


ttXlaPersistOpen
ttXlaGetLSN
ttXlaSetLSN

ttXlaError

Description

Reports details of the error(s) encountered from the previous call on the given handle. Multiple errors may be returned through subsequent calls to ttXlaError. The error stack is cleared following each call to a function other than ttXlaError itself and ttXlaErrorRestart.

See "Handling XLA errors" for a discussion about using this function.

Required privilege

Requires the system privilege XLA.

Syntax

SQLRETURN ttXlaError(ttXlaHandle_h handle,
                     out SQLINTEGER *errCode,
                     out char *errMessage,
                     SQLINTEGER maxLen,
                     out SQLINTEGER *retLen)

Parameters

Parameter Type Description
handle ttXlaHandle_h The transaction log handle for the data store.
errCode out SQLINTEGER * The code of the error message to be copied into the errMessage buffer.
errMessage out char * Buffer to hold the error text.
maxLen SQLINTEGER The maximum length of the errMessage buffer.
retLen out SQLINTEGER * The actual size of the error message.

Returns

SQL_SUCCESS if error information is returned and SQL_NO_DATA_FOUND if no more errors are found in the error stack. If the errMessage buffer is not large enough, ttXlaError returns SQL_SUCCESS_WITH_INFO.

Example

There can be multiple errors on the error stack. This example shows how to read them all.

char message[100];
SQLINTEGER code;

for (;;) {
  rc = ttXlaError(xlahandle, &code, message, sizeof (message), &retLen);
  if (rc == SQL_NO_DATA_FOUND)
      break;
  if (rc == SQL_ERROR) {
      printf("Error in fetching error message\n");
      break;
  }
  else {
      printf("Error code %d: %s\n", code, message);
  }
}

Note

If you use multiple threads to access a TimesTen transaction log over a single XLA connection, TimesTen creates a latch to control concurrent access. If for some reason the latch cannot be acquired by a thread, the XLA function returns SQL_INVALID_HANDLE.

See also

ttXlaErrorRestart


ttXlaErrorRestart

Description

Resets the error stack so that an application can reread the errors. See "Handling XLA errors" for a discussion about using this function.

Required privilege

Requires the system privilege XLA.

Syntax

SQLRETURN ttXlaErrorRestart(ttXlaHandle_h handle)

Parameters

Parameter Type Description
handle ttXlaHandle_h The transaction log handle for the data store.

Returns

SQL_SUCCESS if call is successful. Otherwise, use ttXlaError to report the error.

Example

rc = ttXlaErrorRestart(xlahandle);

See also

ttXlaError


ttXlaGenerateSQL

Description

Generates a SQL DML or DDL statement that expresses the effect of the update record. The generated statement is not applied to any data store or database. Instead, the statement is returned in the given buffer, whose maximum size is specified by the maxLen parameter. The actual size of the buffer is returned in actualLen. For update and delete records, ttXlaGenerateSQL requires a primary key or a unique index on a non-nullable column to generate the correct SQL.

The generated SQL statement is encoded in the connection character set that is associated with the ODBC connection of the XLA handle.

Also see "Replicating updates to a non-TimesTen data store".

Required privilege

Requires the system privilege XLA.

Syntax

SQLRETURN ttXlaGenerateSQL(ttXlaHandle_h handle,
                           ttXlaUpdateDesc_t *record,
                           out char *buffer,
                           SQLINTEGER maxLen,
                           out SQLINTEGER *actualLen)

Parameters

Parameter Type Description
handle ttXlaHandle_h The transaction log handle for the data store.
record ttXlaUpdateDesc_t * The record to be translated into SQL.
buffer out char * Location of the translated SQL statement.
maxLen SQLINTEGER The maximum length of the buffer, in bytes.
actualLen out SQLINTEGER * The actual length of the buffer, in bytes.

Returns

SQL_SUCCESS if call is successful. Otherwise, use ttXlaError to report the error.

Example

This example generates the text of an SQL statement that is equivalent to the UPDATE expressed by an update record:

ttXlaUpdateDesc_t record;
char buffer[200];
/*
 * Get the desired update record into the varable record.
 */

SQLINTEGER actualLength;

rc = ttXlaGenerateSQL(xlahandle, &record, buffer, 200,
                      &actualLength);

Note

The ttXlaGenerateSQL function cannot generate SQL statements for update records associated with a table that has been dropped or altered since the record was generated.

See also


ttXlaApply
ttXlaCommit
ttXlaRollback
ttXlaLookup
ttXlaTableCheck

ttXlaGetColumnInfo

Description

Retrieves information about all the columns in the table. Normally, *nreturned is set to the number of columns returned in colinfo. The systemTableID or userTableID parameter describes the desired table. This call is serialized with respect to changes in the table's definition.

See "Obtaining column descriptions" for a discussion about using this function.

Required privilege

Requires the system privilege XLA.

Syntax

SQLRETURN ttXlaGetColumnInfo(ttXlaHandle_h handle,
                             SQLUBIGINT systemTableID,
                             SQLUBIGINT userTableID,
                             out ttXlaColDesc_t *colinfo,
                             SQLINTEGER maxcols,
                             out SQLINTEGER *nreturned)

Parameters

Parameter Type Description
handle ttXlaHandle_h The transaction log handle for the data store.
systemTableID SQLUBIGINT System ID of table.
userTableID SQLUBIGINT User ID of table.
colinfo out ttXlaColDesc_t * A pointer to the buffer large enough to hold a separate description for maxcols columns.
maxcols SQLINTEGER The maximum number of columns that can be stored in the colInfo buffer. If the table contains more than maxcols columns, an error is returned.
nreturned out SQLINTEGER * The number of columns returned.

Returns

SQL_SUCCESS if call is successful. Otherwise, use ttXlaError to report the error.

Example

For this example, assume the following definitions:

ttXlaColDesc_t colinfo[20];
SQLUBIGINT systemTableID, userTableID;
SQLINTEGER ncols;

To get the description of up to 20 columns using the system table identifier, issue the following call:

rc = ttXlaGetColumnInfo(xlahandle, systemTableID, 0,
                        colinfo, 20, &ncols);

Likewise, the user table identifier can be used:

rc = ttXlaGetColumnInfo(xlahandle, 0, userTableID,
                        colinfo, 20, &ncols);

See "ttXlaColDesc_t" for details and an example on how to access the column data in a returned row.

See also


ttXlaGetTableInfo
ttXlaDecimalToCString
ttXlaDateToODBCCType
ttXlaTimeToODBCCType
ttXlaTimeStampToODBCCType

ttXlaGetLSN

Description

Returns the Current Read log record identifier for the connection specified by handle. See "How bookmarks work" for a discussion about using this function.

Required privilege

Requires the system privilege XLA.

Syntax

SQLRETURN ttXlaGetLSN(ttXlaHandle_h handle,
                      out tt_XlaLsn_t *LSN)

Parameters

Parameter Type Description
handle ttXlaHandle_h The transaction log handle for the data store.
LSN out tt_XlaLsn_t * The Current Read log record identifier for the handle.

Note:

Be aware that tt_XlaLsn_t, particularly the logFile and logOffset fields, is used differently than in earlier releases, referring to log record identifiers rather than sequentially increasing LSNs. See the note in "tt_XlaLsn_t".

Returns

SQL_SUCCESS if call is successful. Otherwise, use ttXlaError to report the error.

Example

This example returns the Current Read log record identifier, CurLSN.

tt_XlaLsn_t CurLSN;

rc = ttXlaGetLSN(xlahandle, &CurLSN);

See also

ttXlaSetLSN


ttXlaGetTableInfo

Description

Retrieves information about the rows in the table; see the description of the ttXlaTblDesc_t data type. If userTableID is nonzero, then it is used to locate the desired table. Otherwise, the systemTableID value is used to locate the table. If both are zero, an error is returned. The description is stored in the output parameter tblinfo. This call is serialized with respect to changes in the table definition.

Required privilege

Requires the system privilege XLA.

Syntax

SQLRETURN ttXlaGetTableInfo(ttXlaHandle_h handle,
                            SQLUBIGINT systemTableID,
                            SQLUBIGINT userTableID,
                            out ttXlaTblDesc_t *tblinfo)

Parameters

Parameter Type Description
handle ttXlaHandle_h The transaction log handle for the data store.
systemTableID SQLUBIGINT System table ID.
userTableID SQLUBIGINT User table ID.
tblinfo out ttXlaTblDesc_t * Row information.

Returns

SQL_SUCCESS if call is successful. Otherwise, use ttXlaError to report the error.

Example

For this example, assume the following definitions:

ttXlaTblDesc_t tabinfo; 
SQLUBIGINT systemTableID, userTableID;

To get table information using a system identifier, find the system table identifier using ttXlaTableByName or other means and issue the call:

rc = ttXlaGetTableInfo(xlahandle, systemTableID, 0, &tabinfo);

Alternatively, the table information can be retrieved using a user table identifier:

rc = ttXlaGetTableInfo(xlahandle, 0, userTableID, &tabinfo);

See also

ttXlaGetColumnInfo


ttXlaGetVersion

Description

This function is used in combination with ttXlaSetVersion to ensure XLA applications written for older versions of XLA operate on a new version. The configured version is typically the older version, while the actual version is the newer one.

ttXlaGetVersion retrieves the currently configured XLA version and stores it into configuredVersion parameter. The actual version of the underlying XLA is stored in actualVersion. Due to calls on ttXlaSetVersion, the results in configuredVersion may vary from one call to the next, but the results in actualVersion remain the same.

See "XLA persistent mode" for a discussion about using this function.

Required privilege

Requires the system privilege XLA.

Syntax

SQLRETURN ttXlaGetVersion(ttXlaHandle_h handle,
                          out ttXlaVersion_t *configuredVersion,
                          out ttXlaVersion_t *actualVersion)

Parameters

Parameter Type Description
handle ttXlaHandle_h The transaction log handle for the data store.
configuredVersion out ttXlaVersion_t * The configured version of XLA.
actualVersion out ttXlaVersion_t * The actual version of XLA.

Returns

SQL_SUCCESS if call is successful. Otherwise, use ttXlaError to report the error.

Example

Assume the following directions for this example:

ttXlaVersion_t configured, actual;

To determine the current version configuration, use the call:

rc = ttXlaGetVersion(xlahandle, &configured, &actual);

See also


ttXlaVersionCompare
ttXlaSetVersion

ttXlaLookup

Description

This function looks for a record in the given table with the key values specified in the keys parameter. The formats of the keys and result record are the same as for ordinary rows. This function requires a primary key on the underlying table.

Required privilege

Requires the system privilege XLA.

Syntax

SQLRETURN ttXlaLookup(ttXlaHandle_h handle,
                      ttXlaTableDesc_t *table,
                      void *keys,
                      out void *result,
                      SQLINTEGER maxsize,
                      out SQLINTEGER *retsize)

Parameters

Parameter Type Description
handle ttXlaHandle_h The transaction log handle for the data store.
table ttXlaTblDesc_t * The table to search.
keys void * A record in the defined structure for the table. Only those columns of the keys record that are part of the primary key for the table are examined.
result out void * The located record is copied into the result. If no record exists with the matching key columns, an error is returned.
maxsize SQLINTEGER The size of the largest record that can fit into the result buffer.
retsize out SQLINTEGER * The actual size of the record.

Returns

SQL_SUCCESS if call is successful. Otherwise, use ttXlaError to report the error.

Example

This example looks up a record given a pair of integer key values. Before this call, table should describe the desired table and keybuffer contains a record with the key columns set.

char keybuffer[100];
char recbuffer[2000];
ttXlaTableDesc_t table;
SQLINTEGER recordSize;

rc = ttXlaLookup(xlahandle, &table, keybuffer, recbuffer,
                 sizeof (recbuffer), &recordSize);

See also


ttXlaApply
ttXlaCommit
ttXlaRollback
ttXlaTableCheck
ttXlaGenerateSQL

ttXlaNextUpdate

Description

This function fetches up to maxrecords update records from the transaction log and returns the records associated with committed transactions to the records buffer. The actual number of returned records is reported in the nreturned output parameter. This function requires a bookmark to be present in the data store and to be associated with the connection used by the function.

When operating the transaction log in persistent mode, each call to ttXlaNextUpdate resets the bookmark to the last record read to enable the next call to ttXlaNextUpdate to return the next list of records.

See "Retrieving update records from the transaction log" for a discussion about using this function.

Required privilege

Requires the system privilege XLA.

Syntax

SQLRETURN ttXlaNextUpdate(ttXlaHandle_h handle,
                          out ttXlaUpdateDesc_t ***records,
                          SQLINTEGER maxrecords,
                          out SQLINTEGER *nreturned)

Parameters

Parameter Type Description
handle ttXlaHandle_h The transaction log handle for the data store.
records out ttXlaUpdateDesc_t *** The buffer to hold the completed transaction records.
maxrecords SQLINTEGER The maximum number of records to be fetched.
nreturned out SQLINTEGER * The actual number of returned records. 0 is returned if no update data is available.

Returns

SQL_SUCCESS if call is successful. Otherwise, use ttXlaError to report the error.

Example

This example retrieves up to 100 records and describes a loop in which each record can be processed:

ttXlaUpdateDesc_t **records;
SQLINTEGER nreturned;
SQLINTEGER i;

rc = ttXlaNextUpdate(xlahandle, &records, 100, &nreturned);
/* Check for errors; if none, process the records */
for (i = 0; i < nreturned; i++) {
  process(records[i]);
}

Notes

Updates are generated for all data definition statements, regardless of tracking status. Updates are generated for data update operations for all tracked tables associated with the bookmark.

In addition, updates are generated for certain special operations, including assigning application-level identifiers for tables and columns and changing a table's tracking status.

See also


ttXlaNextUpdateWait
ttXlaAcknowledge

ttXlaNextUpdateWait

Description

Similar to the ttXlaNextUpdate function, with the addition of a seconds parameter that specifies the number of seconds to wait if no records are available in the transaction log. The actual number of seconds of wait time can be up to two seconds more than the specified seconds value.

Also see "Retrieving update records from the transaction log".

Required privilege

Requires the system privilege XLA.

Syntax

SQLRETURN ttXlaNextUpdateWait(ttXlaHandle_h handle,
                              out ttXlaUpdateDesc_t *** records,
                              SQLINTEGER maxrecords,
                              out SQLINTEGER * nreturned,
                              SQLINTEGER seconds)

Parameters

Parameter Type Description
handle ttXlaHandle_h The transaction log handle for the data store.
records out ttXlaUpdateDesc_t *** The buffer to hold the completed transaction records.
maxrecords SQLINTEGER The maximum number of records to be fetched.

Note: The largest effective value is 1000 records.

nreturned out SQLINTEGER * The actual number of records returned. 0 is returned if no update data is available within the seconds wait period.
seconds SQLINTEGER Number of seconds to wait if the log is empty.

Returns

SQL_SUCCESS if call is successful. Otherwise, use ttXlaError to report the error.

Example

This example retrieves up to 100 records and will wait for up to 60 seconds if there are no records available in the transaction log.

ttXlaUpdateDesc_t **records;
SQLINTEGER nreturned;
SQLINTEGER i;

rc = ttXlaNextUpdateWait(xlahandle, &records, 100,
                         &nreturned, 60);
/* Check for errors; if none, process the records */
for (i = 0; i < nreturned; i++) {
  process(records[i]);
}

See also


ttXlaNextUpdate
ttXlaAcknowledge

ttXlaNumberToBigInt

Description

Converts a TTXLA_NUMBER value to a SQLBIGINT value usable by an application.

Call this function only for a column of type TTXLA_NUMBER. The data type can be obtained from the ttXlaColDesc_t structure returned by the ttXlaGetColumnInfo function.

Required privilege

Requires the system privilege XLA.

Syntax

SQLRETURN ttXlaNumberToBigInt(void *fromData,
                              SQLBIGINT *bint)

Parameters

Parameter Type Description
fromData void * Pointer to the number value returned from the transaction log.
bint SQLBIGINT * The SQLBIGINT value converted from the XLA number value.

Returns

SQL_SUCCESS if successful. Otherwise, use ttXlaError to report an error.


ttXlaNumberToCString

Description

Converts a TTXLA_NUMBER value to a character string usable by an application.

Call this function only for a column of type TTXLA_NUMBER. The data type can be obtained from the ttXlaColDesc_t structure returned by the ttXlaGetColumnInfo function.

Required privilege

Requires the system privilege XLA.

Syntax

SQLRETURN ttXlaNumberToCString(ttXlaHandle_h handle,
                               void *fromData,
                               char *buf,
                               int buflen
                               int *reslen)

Parameters

Parameter Type Description
fromData void * Pointer to the number value returned from the transaction log.
buf char * Location where the converted data is placed.
buflen int Size of the buffer where the converted data is placed.
reslen int * If buflen >= reslen, then reslen is the number of bytes that were written.

If buflen <reslen, then reslen is the number of bytes that would have been written if the buffer had been large enough.


Returns

SQL_SUCCESS if call is successful. Otherwise, use ttXlaError to report the error.


ttXlaNumberToDouble

Description

Converts a TTXLA_NUMBER value to a long floating point number value usable by applications.

Call this function only for a column of type TTXLA_NUMBER. The data type can be obtained from the ttXlaColDesc_t structure returned by the ttXlaGetColumnInfo function.

Required privilege

Requires the system privilege XLA.

Syntax

SQLRETURN ttXlaNumberToDouble(void *fromData,
                              double *dbl)

Parameters

Parameter Type Description
fromData void * Pointer to the number value returned from the transaction log.
dbl double * The long floating point number value converted from the XLA number value.

Returns

SQL_SUCCESS if call is successful. Otherwise, use ttXlaError to report an error.


ttXlaNumberToInt

Description

Converts a TTXLA_NUMBER value to a SQLINTEGER value usable by an application.

Call this function only for a column of type TTXLA_NUMBER. The data type can be obtained from the ttXlaColDesc_t structure returned by the ttXlaGetColumnInfo function.

Required privilege

Requires the system privilege XLA.

Syntax

SQLRETURN ttXlaNumberToInt(void *fromData,
                           SQLINTEGER *ival)

Parameters

Parameter Type Description
fromData void * Pointer to the number value returned from the transaction log.
ival SQLINTEGER * The SQLINTEGER value converted from the XLA number value.

Returns

SQL_SUCCESS if call is successful. Otherwise, use ttXlaError to report an error.


ttXlaNumberToSmallInt

Description

Converts a TTXLA_NUMBER value to a SQLSMALLINT value usable by an application.

Call this function only for a column of type TTXLA_NUMBER. The data type can be obtained from the ttXlaColDesc_t structure returned by the ttXlaGetColumnInfo function.

Required privilege

Requires the system privilege XLA.

Syntax

SQLRETURN ttXlaNumberToSmallInt(void *fromData,
                                SQLSMALLINT *smint)

Parameters

Parameter Type Description
fromData void * Pointer to the number value returned from the transaction log.
smint SQLSMALLINT * The SQLSMALLINT value converted from the XLA number value.

Returns

SQL_SUCCESS if call is successful. Otherwise, use ttXlaError to report an error.


ttXlaNumberToTinyInt

Description

Converts a TTXLA_NUMBER value to a tiny integer value usable by an application.

Call this function only for a column of type TTXLA_NUMBER. The data type can be obtained from the ttXlaColDesc_t structure returned by the ttXlaGetColumnInfo function.

Required privilege

Requires the system privilege XLA.

Syntax

SQLRETURN ttXlaNumberToTinyInt(void *fromData,
                               SQLCHAR *tiny)

Parameters

Parameter Type Description
fromData void * Pointer to the number value returned from the transaction log.
tiny SQLCHAR * The tiny integer value converted from the XLA number value.

Returns

SQL_SUCCESS if call is successful. Otherwise, use ttXlaError to report an error.


ttXlaNumberToUInt

Description

Converts a TTXLA_NUMBER value to an unsigned integer value usable by an application.

Call this function only for a column of type TTXLA_NUMBER. The data type can be obtained from the ttXlaColDesc_t structure returned by the ttXlaGetColumnInfo function.

Required privilege

Requires the system privilege XLA.

Syntax

SQLRETURN ttXlaNumberToInt(void *fromData,
                           SQLUINTEGER *ival)

Parameters

Parameter Type Description
fromData void * Pointer to the number value returned from the transaction log.
ival SQLUINTEGER * The integer value converted from the XLA number value.

Returns

SQL_SUCCESS if call is successful. Otherwise, use ttXlaError to report an error.


ttXlaOpenTimesTen

Description

Initializes a transaction log handle to a TimesTen data store to enable access to the transaction log in non-persistent mode. The hdbc parameter is an ODBC connection handle to a TimesTen data store that will be used to apply updates. Do not issue any other ODBC calls against this connection until it is closed by ttXlaClose. The handle parameter is initialized by this call and must be provided on each subsequent call that applies updates.

In non-persistent mode, only one application can read from the transaction log at any point in time. See "Initializing XLA in non-persistent mode" for related discussion.

Note:

Most applications should use ttXlaPersistOpen to initialize XLA in persistent mode.

Required privilege

Requires the system privilege XLA.

Syntax

SQLRETURN ttXlaOpenTimesTen(SQLHDBC hdbc,
                            out ttXlaHandle_h *handle)

Parameters

Parameter Type Description
hdbc SQLHDBC The ODBC handle for the data store.
handle out ttXlaHandle_h * The transaction log handle for the data store.

Returns

SQL_SUCCESS if call is successful. Otherwise, use ttXlaError to report the error.

The following example opens a transaction log in non-persistent mode and returns a handle named xlahandle for the ODBC connection:

SQLHDBC hdbc; 
ttXlaHandle_h xlahandle;
rc = ttXlaOpenTimesTen(hdbc, &xlahandle);

Note

Use of multiple threads over the same XLA handle is not recommended by TimesTen. Multithreaded applications should use ttXlaPersistOpen to create a separate XLA handle for each thread. If multiple threads must use the same XLA handle, use a mutex to serialize thread access to that XLA handle so that only one thread can execute an XLA operation at a time.

See also


ttXlaConfigBuffer
ttXlaStatus
ttXlaResetStatus
ttXlaClose

ttXlaOraDateToODBCTimeStamp

Description

Converts a TTXLA_DATE value to an ODBC timestamp.

Call this function only for a column of type TTXLA_DATE. The data type can be obtained from the ttXlaColDesc_t structure returned by the ttXlaGetColumnInfo function.

Required privilege

Requires the system privilege XLA.

Syntax

SQLRETURN ttXlaOraDateToODBCTimeStamp(void *fromData,
                                      TIMESTAMP_STRUCT *returnData)

Parameters

Parameter Type Description
fromData void * Pointer to the number value returned from the transaction log.
returnData TIMESTAMP_STRUCT * An ODBC timestamp value converted from the XLA Oracle DATE value.

Returns

SQL_SUCCESS if call is successful. Otherwise, use ttXlaError to report an error.


ttXlaOraTimeStampToODBCTimeStamp

Description

Converts a TTXLA_TIMESTAMP value to an ODBC timestamp.

Call this function only for a column of type TTXLA_TIMESTAMP. The data type can be obtained from the ttXlaColDesc_t structure returned by the ttXlaGetColumnInfo function.

Syntax

SQLRETURN ttXlaOraTimeStampToODBCTimeStamp(void *fromData,
                                           TIMESTAMP_STRUCT *returnData)

Required privilege

Requires the system privilege XLA.

Parameters

Parameter Type Description
fromData void * Pointer to the number value returned from the transaction log.
returnData TIMESTAMP_STRUCT * An ODBC timestamp value converted from the XLA Oracle TIMESTAMP value.

Returns

SQL_SUCCESS if call is successful. Otherwise, use ttXlaError to report an error.


ttXlaPersistOpen

Description

Initializes a transaction log handle to a TimesTen data store to enable access to the transaction log in persistent mode. The hdbc parameter is an ODBC connection handle to a TimesTen data store. Create only one XLA handle for each ODBC connection. After you have created an XLA handle on an ODBC connection, do not issue any other ODBC calls over the ODBC connection until it is closed by ttXlaClose.

The tag is a string that identifies the persistent bookmark (see "About XLA bookmarks"). The tag can identify a new bookmark, either non-replicated or replicated, or one that already exists in the system, as specified by the options parameter. The handle parameter is initialized by this call and must be provided on each subsequent call to XLA.

Some actions can be done without a bookmark. When performing these types of actions, you can use the XLANONE option to access the transaction log without a bookmark. Actions that cannot be done without a bookmark are the following:

In persistent mode, multiple applications can concurrently read from the transaction log. See "Initializing XLA and obtaining an XLA handle" for a discussion about using this function.

When this function is successful, XLA sets the autocommit mode to off.

If this function fails but still creates a handle, the handle must be closed to prevent memory leaks.

Required privilege

Requires the system privilege XLA.

Syntax

SQLRETURN ttXlaPersistOpen(SQLHDBC hdbc,
                           SQLCHAR * tag,
                           SQLUINTEGER options,
                           out ttXlaHandle_h * handle)

Parameters

Parameter Type Description
hdbc SQLHDBC The ODBC handle for the data store.
tag SQLCHAR * The identifier for the persistent bookmark. Can be null, in which case options should be set to XLANONE. Maximum allowed length is 31.
options SQLUINTEGER Bookmark options:
  • XLANONE: Connect without a bookmark. The tag field is ignored.

  • XLACREAT: Create a new non-replicated bookmark. Fails if a bookmark already exists.

  • XLAREPL: Create a new replicated bookmark. Fails if a bookmark already exists.

  • XLAREUSE: Associate with an existing bookmark (non-replicated or replicated). Fails if the bookmark does not exist.

handle out ttXlaHandle_h * The transaction log handle returned by this call. Space is allocated by this call. User should call ttXlaClose to free space.

Returns

SQL_SUCCESS if call is successful. Otherwise, use ttXlaError to report the error.

Example

This example opens a transaction log in persistent mode, returns a handle named xlahandle, and creates a new non-replicated bookmark named mybookmark:

SQLHDBC hdbc;
ttXlaHandle_h xlahandle;

rc = ttXlaPersistOpen(hdbc, ( SQLCHAR*)mybookmark,
                      XLACREAT, &xlahandle);

Alternatively, create a new replicated bookmark as follows:

SQLHDBC hdbc;
ttXlaHandle_h xlahandle;

rc = ttXlaPersistOpen(hdbc, ( SQLCHAR*)mybookmark,
                      XLAREPL, &xlahandle);

Note

Multithreaded applications should create a separate XLA handle for each thread. If multiple threads must use the same XLA handle, use a mutex to serialize thread access to that XLA handle so that only one thread can execute an XLA operation at a time.

See also


ttXlaClose
ttXlaDeleteBookmark
ttXlaGetLSN
ttXlaSetLSN

ttXlaResetStatus

Description

This function is valid only when XLA is in non-persistent mode.

Resets all the XLA status counters reported in the ttXlaStatus_t structure returned by ttXlaStatus. Currently, only the xlabufminfree value is reset.

Required privilege

Requires the system privilege XLA.

Syntax

SQLRETURN ttXlaResetStatus(ttXlaHandle_h handle)

Parameters

Parameter Type Description
handle ttXlaHandle_h The transaction log handle for the data store.

Returns

SQL_SUCCESS if call is successful. Otherwise, use ttXlaError to report the error.

Example

The following example resets the XLA status counters:

rc = ttXlaResetStatus(xlahandle);

See also


ttXlaOpenTimesTen
ttXlaConfigBuffer
ttXlaStatus

ttXlaRollback

Description

Rolls back the current transaction being applied on the handle. You can call this routine to respond to transient errors (timeout or deadlock) reported by ttXlaApply.

See "Handling timeout and deadlock errors" for a discussion about using this function.

Required privilege

Requires the system privilege XLA.

Syntax

SQLRETURN ttXlaRollback(ttXlaHandle_h handle)

Parameters

Parameter Type Description
handle ttXlaHandle_h The transaction log handle for the data store.

Returns

SQL_SUCCESS if call is successful. Otherwise, use ttXlaError to report the error.

Example

rc = ttXlaRollback(xlahandle);

See Also


ttXlaApply
ttXlaCommit
ttXlaLookup
ttXlaTableCheck
ttXlaGenerateSQL

ttXlaRowidToCString

Description

Converts a ROWID value to a string value usable by applications.

Required privilege

Requires the system privilege XLA.

Syntax

SQLRETURN ttXlaRowidToCString(void *fromData, char *buf, int buflen)

Parameters

Parameter Type Description
fromData void * Pointer to the ROWID value returned from the transaction log.
buf char * Pointer to storage allocated to hold the converted string.
buflen int Length of the converted string.

Returns

SQL_SUCCESS if call is successful. Otherwise, use ttXlaError to report the error.

Example

char charbuf[18];
void * rowiddata;
/* ... */
rc = ttXlaRowidToCString(rowiddata, charbuf, sizeof(charbuf));

ttXlaSetLSN

Description

Sets the Current Read log record identifier for the data store specified by handle. The specified LSN value should be returned from ttXlaGetLSN. It cannot be a user-created value and cannot be earlier than the current bookmark's Initial Read log record identifier.

See "About XLA bookmarks" for a discussion about using this function.

Required privilege

Requires the system privilege XLA.

Syntax

SQLRETURN ttXlaSetLSN(ttXlaHandle_h handle,
                      tt_XlaLsn_t *LSN)

Parameters

Parameter Type Description
handle ttXlaHandle_h The transaction log handle for the data store.
LSN tt_XlaLsn_t * The new log record identifier for the handle.

Note:

Be aware that tt_XlaLsn_t, particularly the logFile and logOffset fields, is used differently than in earlier releases, referring to log record identifiers rather than sequentially increasing LSNs. See the note in "tt_XlaLsn_t".

Returns

SQL_SUCCESS if call is successful. Otherwise, use ttXlaError to report the error.

Example

This example sets the Current Read log record identifier to CurLSN.

tt_XlaLsn_t CurLSN;

rc = ttXlaSetLSN(xlahandle, &CurLSN);

See also

ttXlaGetLSN


ttXlaSetVersion

Description

Sets the version of XLA to be used by the application. This version must be either the same as the version received from ttXlaGetVersion or from an earlier version.

See "XLA persistent mode" for a discussion about using this function.

Required privilege

Requires the system privilege XLA.

Syntax

SQLRETURN ttXlaSetVersion(ttXlaHandle_h handle,
                          ttXlaVersion_t *version)

Parameters

Parameter Type Description
handle ttXlaHandle_h The transaction log handle for the data store.
version ttXlaVersion_t * The desired version of XLA.

Returns

SQL_SUCCESS if call is successful. Otherwise, use ttXlaError to report the error.

Example

To set the configured version to the value specified in requestedVersion, issue the call:

rc = ttXlaSetVersion(xlahandle, &requestedVersion);

See also


ttXlaVersionCompare
ttXlaGetVersion

ttXlaStatus

Description

This function is valid only when operating XLA in non-persistent mode.

Retrieves status information on the transaction log buffer and your XLA staging buffer and stores it in the *status parameter, which is of data type ttXlaStatus_t. This data structure includes:

The ttXlaStatus_t ->xlabufminfree value is the minimum number of free bytes in the transaction log buffer and is a useful statistic if you decide to recalculate the optimum size of the staging buffer. As the transaction log buffer expands and contracts, xlabufminfree may no longer accurately reflect the minimum space. You can call ttXlaResetStatus, generally used to reset the value of the ttXlaStatus_t ->xlabufminfree field, to null xlabufminfree. Then, at some later time, you can call ttXlaStatus to obtain a new minimum value before calculating the optimum newSize value to pass to the ttXlaConfigBuffer function.

Required privilege

Requires the system privilege XLA.

Syntax

ttXlaStatus(ttXlaHandle_h handle, out ttXlaStatus_t *status)

Parameters

Parameter Type Description
handle ttXlaHandle_h The transaction log handle for the data store.
status out ttXlaStatus_t * The current XLA status.

Returns

SQL_SUCCESS if call is successful. Otherwise, use ttXlaError to report the error.

Example

This example gets the current XLA status:

ttXlaStatus_t s;
rc = ttXlaStatus(xlahandle, &s);

See also


ttXlaOpenTimesTen
ttXlaConfigBuffer
ttXlaResetStatus

ttXlaTableByName

Description

Finds the system and user table identifiers for a table or materialized view by providing the owner and name of the table or view. See "Specifying which tables to monitor for updates" for a discussion about using this function.

Required privilege

Requires the system privilege XLA.

Syntax

SQLRETURN ttXlaTableByName(ttXlaHandle_h handle,
                           char *owner,
                           char *name,
                           out SQLUBIGINT *sysTableID,
                           out SQLUBIGINT *userTableID)

Parameters

Parameter Type Description
handle ttXlaHandle_h The transaction log handle for the data store.
owner char * The owner for the table or view as a string.
name char * The name of the table or view.
sysTableID out SQLUBIGINT * Where the system table ID is returned.
userTableID out SQLUBIGINT * Where the user table ID is returned.

Returns

SQL_SUCCESS if call is successful. Otherwise, use ttXlaError to report the error.

Example

To get the system and user table ID's associated with the table PURCHASING.INVOICES, use the call:

SQLUBIGINT sysTableID;
SQLUBIGINT userTableID;

rc = ttXlaTableByName(xlahandle, "PURCHASING", "INVOICES", 
                      &sysTableID, &userTableID);

See also

ttXlaTableStatus


ttXlaTableCheck

Description

When using XLA as a replication mechanism, this function verifies that the named table in the ttXlaTblDesc_t structure received from a master data store is compatible with a subscriber data store or database associated with the handle. The compat parameter indicates whether the tables are compatible.

See "Checking table compatibility between data stores" for a discussion about using this function.

Required privilege

Requires the system privilege XLA.

Syntax

SQLRETURN ttXlaTableCheck(ttXlaHandle_h handle,
                          ttXlaTblDesc_t *table,
                          ttXlaColDesc_t *columns,
                          out SQLINTEGER *compat)

Parameters

Parameter Type Description
handle ttXlaHandle_h The transaction log handle for the data store.
table ttXlaTblDesc_t * A table description.
columns ttXlaColDesc_t * Column description for the table.
compat out SQLINTEGER * Returns compatibility information.
  • 1: Tables are compatible.

  • 0: Tables are not compatible.


Returns

SQL_SUCCESS if call is successful. Otherwise, use ttXlaError to report the error.

Example

This example checks the compatibility of a table:

SQLINTEGER compat;
ttXlaTblDesc_t table;
ttXlaColDesc_t columns[20];
/*
 * Get the desired table and column definitions into
 * the variables "table" and "columns"
 */
rc = ttXlaTableCheck(xlahandle, &table, columns, &compat);
if (compat) {
    /*
     * Compatible
     */
}
else {
    /*
     * Not compatible or some other error occurred
     */
}

See also


ttXlaApply
ttXlaCommit
ttXlaRollback
ttXlaLookup
ttXlaGenerateSQL

ttXlaTableStatus

Description

Returns the update status for a table in *oldstatus. You identify the table by specifying either a user ID (userTableID) or a system ID (systemTableID). If userTableID is nonzero, it is used to locate the table. Otherwise systemTableID is used. If both are zero, an error is returned.

Specifying a value for newstatus sets the update status to *newstatus. A nonzero status means the table specified by systemTableID is available through XLA. Zero means the table is not tracked. Changes to table update status are effective immediately.

Updates to a table are tracked only if update tracking was enabled for the table at the time the update was performed. This call is serialized with respect to updates to the underlying table. Therefore, transactions that update the table run either completely before or completely after the change to table status.

To use ttXlaTableStatus, the user must be connected to a bookmark in persistent mode. ttXlaTableStatus reports inserts, updates, and deletes only to the bookmark that has subscribed to the table. It reports DDL events to all bookmarks. DDL events include CREATAB, DROPTAB, CREAIND, DROPIND, CREATVIEW, DROPVIEW, CREATSEQ, DROPSEQ, ADDCOLS, DRPCOLS, TRUNCATE, SETTBL1, and SETCOL1 transactions.

See "Specifying which tables to monitor for updates" for a discussion about using this function.

Required privilege

Requires the system privilege XLA.

Syntax

SQLRETURN ttXlaTableStatus(ttXlaHandle_h handle,
                           SQLUBIGINT systemTableID,
                           SQLUBIGINT userTableID,
                           out SQLINTEGER *oldstatus,
                           SQLINTEGER *newstatus)

Parameters

Parameter Type Description
handle ttXlaHandle_h The transaction log handle for the data store.
systemTableID SQLUBIGINT System ID of table.
userTableID SQLUBIGINT User ID of table.
oldstatus out SQLINTEGER * XLA status: 1 = On or 0 = Off.
newstatus SQLINTEGER * XLA status: 1 = On or 0 = Off.

Returns

SQL_SUCCESS if call is successful. Otherwise, use ttXlaError to report the error.

Example

The following examples assume that the system or user table identifiers are found using ttXlaTableByName or some other means.

Assume these declarations for the example:

SQLUBIGINT systemTableID;
SQLUBIGINT userTableID;
SQLINTEGER currentStatus, requestedStatus;

To find the status of a table given its system table identifier, use the call:

/* Get system table identifier into systemTableID, then ... */

rc = ttXlaTableStatus(xlahandle, systemTableID, 0,
                      &currentStatus, NULL);

The currentStatus value will be nonzero if update tracking for the table is enabled, or zero otherwise.

To enable update tracking for a table given a system table identifier, set the requested status to 1 as follows:

requestedStatus = 1;

rc = ttXlaTableStatus(xlahandle, systemTableID, 0,
                      NULL, &requestedStatus);

You can set a new update tracking status and retrieve the current status in a single call, as in this example:

requestedStatus = 1;

rc = ttXlaTableStatus(xlahandle, systemTableID, 0,
                      &currentStatus, &requestedStatus);

The above call enables update tracking for a table by system table identifier and retrieves the prior update tracking status in the variable currentStatus.

All of these examples can be done using user table identifiers as well. To retrieve the update tracking status of a table by means of its user table identifier, use the following call:

/* Get system table identifier into userTableID, then ... */

rc = ttXlaTableStatus(xlahandle, 0, userTableID,
                      &currentStatus, NULL);

See also

ttXlaTableByName


ttXlaTimeToODBCCType

Description

Converts a TTXLA_TIME value to an ODBC C value usable by applications. See "Converting complex data types" for a discussion about using this function.

Call this function only for a column of type TTXLA_TIME. The data type can be obtained from the ttXlaColDesc_t structure returned by the ttXlaGetColumnInfo function.

Required privilege

Requires the system privilege XLA.

Syntax

SQLRETURN ttXlaTimeToODBCCType (void *fromData,
                                out TIME_STRUCT *returnData)

Parameters

Parameter Type Description
fromData void * Pointer to the time value returned from the transaction log.
returnData out TIME_STRUCT * Pointer to storage allocated to hold the converted time.

Returns

SQL_SUCCESS if call is successful. Otherwise, use ttXlaError to report the error.

Example

This example assumes you have used the offset value returned in a ttXlaColDesc_t structure to obtain a time value, pColVal, from a row returned in a transaction log record.

TIME_STRUCT time;

rc = ttXlaTimeToODBCCType(pColVal, &time);

ttXlaTimeStampToODBCCType

Description

Converts a TTXLA_TIMSTAMP_TT value to an ODBC C value usable by applications. See "Converting complex data types" for a discussion about using this function.

Call this function only for a column of type TTXLA_TIMSTAMP_TT. The data type can be obtained from the ttXlaColDesc_t structure returned by the ttXlaGetColumnInfo function.

Required privilege

Requires the system privilege XLA.

Syntax

SQLRETURN ttXlaTimeStampToODBCCType(void *fromData,
                                    out TIMESTAMP_STRUCT *returnData)

Parameters

Parameter Type Description
fromData void * Pointer to the timestamp value returned from the transaction log.
returnData out TIMESTAMP_ STRUCT * Pointer to storage allocated to hold the converted timestamp.

Returns

SQL_SUCCESS if successful. Otherwise, use ttXlaError to report the error.

Example

This example assumes you have used the offset value returned in a ttXlaColDesc_t structure to obtain a timestamp value, pColVal, from a row returned in a transaction log record.

TIMESTAMP_STRUCT timestamp;

rc = ttXlaTimeStampToODBCCType(pColVal, &timestamp);

ttXlaTableVersionVerify

Description

Verifies that the cached table definitions are compatible with the XLA record being processed. Table definitions change only when the ALTER TABLE statement is used to add or remove columns.

You can monitor the XLA stream for XLA records of transaction type ADDCOLS and DRPCOLS to avoid the overhead of using this function. When an XLA record of transaction type ADDCOLS or DROPCOLS is encountered, refresh the table and column definitions. See "Inspecting record headers and locating row addresses" for information about monitoring XLA records for transaction type.

Required privilege

Requires the system privilege XLA.

Syntax

SQLRETURN ttXlaTableVersionVerify(ttXlaHandle_h handle
                                  ttXlaTblVerDesc_t *table,
                                  ttXlaUpdateDesc_t *record
                                  out SQLINTEGER *compat)

Returns

SQL_SUCCESS if cached table definition is compatible with the XLA record being processed. Otherwise, use ttXlaError to report the error.

Parameters

Parameter Type Description
handle ttXlaHandle_h The transaction log handle for the data store.
table ttXlaTblVerDesc_t * A cached table description.
record ttXlaUpdateDesc_t * The XLA record that must be processed.
compat out SQLINTEGER * Returns compatibility information.
  • 1: Tables are compatible.

  • 0: Tables are not compatible.


Example

This example checks the compatibility of a table.

SQLINTEGER compat;
ttXlaTbVerDesc_t table;
ttXlaUpdateDesc_t* record;
/*
 * Get the desired table definitions into the variable "table"
 */
rc = ttXlaTableVersionVerify(xlahandle, &table, record, &compat);
if (compat) {
/*
 * Compatible
 */
}
else {
/*
 * Not compatible or some other error occurred
 * If not compatible, issue a call to ttXlaVersionTableInfo and
 * ttXlaVersionColumnInfo to get the new definition.
 */
}

See also


ttXlaVersionColumnInfo
ttXlaVersionTableInfo

ttXlaVersionColumnInfo

Description

Retrieves information about the columns in a table for which a change update XLA record must be processed.

Required privilege

Requires the system privilege XLA.

Syntax

SQLRETURN ttXlaVersionColumnInfo(ttXlaHandle_h handle,
                                 ttXlaUpdateDesc_t *record,
                                 out ttXlaColDesc_t *colinfo,
                                 SQLINTEGER maxcols,
                                 out SQLINTEGER *nreturned)

Returns

SQL_SUCCESS if call is successful. Otherwise, use ttXlaError to report the error.

Parameters

Parameter Type Description
handle ttXlaHandle_h The transaction log handle for the data store.
record ttXlaUpdateDesc_t * The XLA record that must be processed.
colinfo out ttXlaColDesc_t * A pointer to the buffer large enough to hold a description for maxcols columns.
maxcols SQLINTEGER The maximum number of columns the table can have. If the table contains more than maxcols columns, an error is returned.
nreturned out SQLINTEGER * The number of columns returned.

Example

For this example, assume the following definitions:

ttXlaHandle_h xlahandle
ttXlaUpdateDesc_t *record;
ttXlaColDesc_t colinfo[20];
SQLINTEGER ncols;

The following call retrieves the description of up to 20 columns:

rc = ttXlaVersionColumnInfo(xlahandle, record, colinfo, 20, &ncols);

ttXlaVersionCompare

Description

Compares two XLA versions and returns the result.

Required privilege

Requires the system privilege XLA.

Syntax

SQLRETURN ttXlaVersionCompare(ttXlaHandle_h handle,
                              ttXlaVersion_t *version1,
                              ttXlaVersion_t *version2,
                              out SQLINTEGER *comparison)

Parameters

Parameter Type Description
handle ttXlaHandle_h The transaction log handle for the data store.
version1 ttXlaVersion_t * The version of XLA you want to compare with version2.
version2 ttXlaVersion_t * The version of XLA you want to compare with version1.
comparison out SQLINTEGER * The comparison result.
  • 0: Indicates version1 and version2 match.

  • -1: Indicates version1 is earlier than version2.

  • +1: Indicates version1 is later than version2.


Returns

SQL_SUCCESS if call is successful. Otherwise, use ttXlaError to report the error.

Example

To compare the configured version against the actual version of XLA, issue this call:

ttXlaVersion_t configured, actual;
SQLINTEGER comparision;

rc = ttXlaGetVersion (xlahandle, &configured, &actual);
rc = ttXlaVersionCompare (xlahandle, &configured, &actual,
                          &comparison);

Notes

When connecting two systems with XLA-based replication, we recommend the following protocol:

  1. At the primary site, retrieve the XLA version using ttXlaGetVersion. Send this version information to the standby site.

  2. At the standby site, retrieve the XLA version using ttXlaGetVersion. Use ttXlaVersionCompare to determine which version is earlier. The earlier version number must be used to ensure proper operation between the two sites. Use ttXlaSetVersion to specify the version of the interface to use at the standby site. Send the earlier version number back to the primary site.

  3. When the chosen version is received at the primary site, use ttXlaSetVersion to specify the version of XLA to use.

See also


ttXlaGetVersion
ttXlaSetVersion

ttXlaVersionTableInfo

Description

Retrieves the table definition for the change update record that must be processed. The table description is stored in the tableinfo output parameter.

Required privilege

Requires the system privilege XLA.

Syntax

SQLRETURN ttXlaVersionTableInfo(ttXlaHandle_h handle,
                                ttXlaUpdateDesc_t *record,
                                out ttXlaTblVerDesc_t *tblinfo)

Returns

SQL_SUCCESS if call is successful. Otherwise, use ttXlaError to report the error.

Parameters

Parameter Type Description
handle ttXlaHandle_h The transaction log handle for the data store.
record ttXlaUpdateDesc_t * The XLA record that must be processed.
tableinfo out ttXlaTblVerDesc_t * Information about table definition.

Example

For this example, assume the following definitions:

ttXlaHandle_h xlahandle;
ttXlaUpdateDesc_t *record;
ttXlaTblVerDesc_t tabinfo;

The following call retrieves a table definition:

rc = ttXlaVersionTableInfo(xlahandle, record, &tabinfo);

C data structures used by XLA

This section describes the C data structures used by the XLA functions described in this chapter. These structures are defined in the following file:

install_dir/include/tt_xla.h

You must include this file when building your XLA application.

Table 9-1 Summary of C data structures

C data structure Description

ttXlaNodeHdr_t

Describes the record type. Used at the beginning of records returned by XLA.

ttXlaUpdateDesc_t

Describes an update record.

ttXlaStatus_t

Describes XLA status information returned by ttXlaStatus.

ttXlaVersion_t

Describes XLA version information returned by ttXlaGetVersion.

ttXlaTblDesc_t

Describes table information returned by ttXlaGetTableInfo.

ttXlaTblVerDesc_t

Describes table version returned by ttXlaVersionTableInfo.

ttXlaColDesc_t

Describes table column information returned by ttXlaGetColumnInfo.

tt_LSN_t

Description of a log record identifier used by bookmarks. This structure is used by the ttXlaUpdateDesc_t structure.

tt_XlaLsn_t

Describes a log record identifier used by an XLA bookmark.



ttXlaNodeHdr_t

Most C data structures begin with a standard header that describes the data record type and length. The standard header has the type ttXlaNodeHdr_t.

This header includes the fields:

Field Type Description
nodeType char The type of record:
  • TTXLANHVERSION - Version

  • TTXLANHUPDATE - Update

  • TTXLANHTABLEDESC - Table description

  • TTXLANHCOLDESC - Column description

  • TTXLANHSTATUS - Status

  • TTXLANHINVALID - Invalid

byteOrder char Byte order of the record.
  • 1 - Big-endian

  • 2 - Little-endian

length SQLUINTEGER Total length of record, including all attachments.


ttXlaUpdateDesc_t

This structure describes an update operation to a single row (or tuple) in the data store. Each update record returned by a ttXlaNextUpdate or ttXlaNextUpdateWait function begins with a fixed length ttXlaUpdateDesc_t header followed by zero to two rows from the data store. The row data differs depending on the record type reported in the ttXlaUpdateDesc_t header:

Note:

SETREPL, SETTBLI and SETCOLI records are not returned in persistent mode.

The flags field is a bit-map of special options for the record update.

The connID field identifies the ODBC connection handle that initiated the update. This value can be used to determine if updates came from the same connection.

A separate commit XLA record is generated when a call to the ttApplicationContext procedure is not followed by an operation that generates an XLA record. See "Passing application context" for a description of the ttApplicationContext procedure.

Note

XLA cannot receive notification of:

The only XLA records that can be generated from an ALTER TABLE operation are of type:

While SEQUENCE creates (CREATESEQ) and drops (DROPSEQ) are visible through XLA, SEQUENCE increments are not.

All deletes from cascading deletes are visible through XLA; deletes from aging are visible through XLA. The flags value (discussed in the following table) indicates when deletes are due to cascading or aging.

The fields of the update header defined by ttXlaUpdateDesc_t are as follows.

Field Type Description
header ttXlaNodeHdr_t Standard data header
type SQLUSMALLINT Record type:
  • CREATAB - Create table.

  • DROPTAB - Drop table.

  • CREAIND - Create index.

  • DROPIND - Drop index.

  • CREATVIEW - Create view.

  • DROPVIEW - Drop view.

  • CREATSEQ - Create sequence.

  • DROPSEQ - Drop sequence.

  • ADDCOLS - Add columns.

  • DRPCOLS - Drop columns.

  • SETREPL - Set table replication status.

  • SETTBLI - Set table user ID.

  • SETCOLI - Set column user ID.

  • TRUNCATE - Truncate table.

  • INSERTTUP - Insert.

  • UPDATETUP - Update.

  • DELETETUP - Delete.

  • COMMITONLY - Commit.

flags SQLUSMALLINT Special options on record update:
  • TT_UPDCOMMIT - Indicates that the update record is the last record for the transaction. (Implied commit.)

  • TT_UPDFIRST - Indicates that the update record is the first record for the transaction.

  • TT_UPDREPL - Indicates that this update was the result of a non-XLA TimesTen replicated update from another data store.

  • TT_UPDCOLS - Indicates the presence of a list following the last returned row that specifies which columns in the row were updated. The list consists of an array of SQLUSMALLINT values, the first of which is the number of columns that were updated, followed by the column numbers of the updated columns. For example, if the first and third columns are updated, the array is (2, 1, 3) or (2, 3, 1), depending on the UPDATE statement used. This array is included with all UPDATETUP records.

  • TT_UPDDEFAULT - Indicates that the update record (either a CREATAB or ADDCOLS) contains default column values. If set, the default columns are presented as an array of SQLUSMALLINT values followed by a string with all the default values concatenated. The number of SQLUSMALLINT values in the array is equal to the number of columns in the CREATAB or ADDCOLS record.

  • TT_CASCDEL - Indicates that the XLA update was generated as part of a cascade delete operation.

  • TT_AGING - Indicates that the XLA update was generated as part of an aging operation.

If the value of a specific column is 0, it indicates that column does not have a default value. The defaults for all nonzero values are concatenated in a string and are presented in order, with the array value indicating the length of the default value. For example, three columns with defaults "1" of type INTEGER, no default, and "apple" of type VARCHAR2(10) is (1,0,5)"1apple".

Decimal values for each of these flags bits is as follows. (Note that some flag values are for internal use only.)

TT_UPDCOMMIT     1
TT_UPDFIRST      2
TT_UPDREPL       4
TT_UPDCOLS       8
TT_UPDDEFAULT   64
TT_CASCDEL     256
TT_AGING       512
contextOffset SQLUINTEGER Offset to application-provided context value. This value is 0 if there is no context. A nonzero value indicates the location of the context relative to the beginning of the XLA record.
connID SQLUBIGINT Connection ID owning the transaction.
sysTableID SQLUBIGINT System-provided identifier of the affected table.
userTableID SQLUBIGINT Application-defined table ID of the affected table.
tranID SQLUBIGINT Read-only, system-provided transaction identifier.
LSN tt_LSN_t Transaction log record identifier of this operation, used for diagnostics.
tuple1 SQLUINTEGER Length of first row (tuple) or zero.
tuple2 SQLUINTEGER Length of second row (tuple) or zero.

Note:

Be aware that tt_LSN_t, particularly the logFile and logOffset fields, is used differently than in earlier releases, referring to log record identifiers rather than sequentially increasing LSNs. See the note in "tt_LSN_t".

Special update data formats

The data contained in an update record follows the ttXlaTblDesc_t header. This section describes the data formats for the special update records related to specific SQL operations.

CREATE TABLE

For CREATE TABLE, the special row value consists of the ttXlaTblDesc_t record describing the new table, followed by the ttXlaColDesc_t records that describe each column.


ALTER TABLE

For ALTER TABLE, the special row value consists of a ttXlaDropTableTup_t or ttXlaAddColumnTup_t value, followed by a ttXlaColDesc_t record that describes the column.


ttXlaDropTableTup_t

For a DROP TABLE operation, the row value is as follows:

Field Type Description
tblName char(31) Name of the dropped table.
tblOwner char(31) Owner of the dropped table.


ttXlaTruncateTableTup_t

For a TRUNCATE TABLE operation, the row value is as follows:

Field Type Description
tblName char(31) Name of the truncated table
tblOwner char(31) Owner of the truncated table.


ttXlaCreateIndexTup_t

For a CREATE INDEX operation, the row value is as follows:

Field Type Description
tblName char(31) Name of the table on which the index is defined.
tblOwner char(31) Owner of the table on which the index is defined.
ixName char(31) Name of the new index.
flag char(31) Index flag:
  • P = Primary

  • F = Foreign

  • R = Regular

nixcols SQLUINTEGER Number of indexed columns.
ixColsSys SQLUINTEGER(16) Indexed column numbers using system numbers.
ixColsUser SQLUINTEGER(16) Indexed column numbers using user-defined column IDs.
ixType char 'T' = range, 'H' = hash.
ixUnique char 'U' = unique index, 'N' = non-unique.
pages SQLUINTEGER Number of pages for hash indexes.


ttXlaDropindexTup_t

For a DROP INDEX operation, the row value is as follows:

Field Type Description
tblName char(31) Name of the table on which the index was dropped.
tblOwner char(31) Owner of the table on which the index was dropped.
ixName char(31) Name of the dropped index.


ttXlaAddColumnTup_t

For add columns, the row value is as follows:

Field Type Description
ncols SQLUINTEGER The number of additional columns.

Following this special row are the ttXlaColDesc_t records describing the new columns.


ttXlaDropColumnTup_t

For drop columns, the row value is as follows:

Field Type Description
ncols SQLUINTEGER The number of dropped columns.

Following this special row is an array of ttXlaColDesc_t records describing the columns that were dropped.


ttXlaCreateSeqTup_t

For a CREATE SEQUENCE operation, the row value is as follows:

Field Type Description
sqName char(31) Name of sequence.
sqOwner char(31) Owner of sequence.
cycle char Indicates whether the sequence number generator will continue to generate numbers after it reaches the maximum or minimum value.Values are:
  • 1 = Cycle.

  • 0 = Do not cycle.

minval SQLBIGINT Minimum value of sequence.
maxval SQLBIGINT Maximum value of sequence.
incr SQLBIGINT Increment between sequence numbers. Positive numbers indicate an ascending sequence and negative numbers indicate a descending sequence. In a descending sequence, the range goes from maxval to minval. In an ascending sequence, the range goes from minval to maxval.


ttXlaDropSeqTup_t

For a DROP SEQUENCE operation, the row value is as follows:

Field Type Description
sqName char(31) Name of sequence.
sqOwner char(31) Owner of sequence.


ttXlaViewDesc_t

For a CREATE MATERIALIZED VIEW operation, the row value is as follows:

Field Type Description
vwName char(31) Name of materialized view.
vwOwner char(31) Owner of materialized view.
sysTableID SQLUBIGINT System table ID stored in SYS.TABLES.


ttXlaDropViewTup_t

For a DROP VIEW operation on a materialized view, the row value is as follows:

Field Type Description
vwName char(31) Name of materialized view.
vwOwner char(31) Owner of materialized view.


ttXlaSetTableTup_t

The description of the set table ID operation uses the previously assigned application table identifier in the main part of the update record and provides the new value of the application table identifier in the following special row.

Field Type Description
newID SQLUBIGINT The new user defined table ID.


ttXlaSetColumnTup_t

The description of the set column ID operation provides the following special row:

Field Type Description
oldUserColID SQLUINTEGER Previous user defined column ID value.
newUserColID SQLUINTEGER New user defined column ID value.
sysColID SQLUINTEGER System column ID.


ttXlaSetStatusTup_t

A change in a table's replication status provides the following special row:

Field Type Description
oldStatus SQLUINTEGER Previous replication status.
newStatus SQLUINTEGER New replication status.


Locating the row data following a ttXlaUpdateDesc_t header

See "Retrieving update records from the transaction log" and "Inspecting record headers and locating row addresses" for a detailed discussion on obtaining update records and inspecting the contents of ttXlaUpdateDesc_t headers. Below is a summary of these procedures.

The update header is immediately followed by the row data. The row data is stored in an internal format with the offsets given in the ttXlaColDesc_t structure returned by ttXlaGetColumnInfo.

You can locate the address of the row data by adding the address of the update header to its size.

For example:

char *Row = (char*)&ttXlaUpdateDesc_t +
             sizeof(ttXlaUpdateDesc_t);

For UPDATETUP records, there are two rows of data following the ttXlaUpdateDesc_t header. The first row contains the data before the update, and the second row the data after the update.

Since the new row is right after the old row, you can calculate its address by adding the address of the old row to its length (tuple1).

For example:

char *oldRow = (char*)&ttXlaUpdateDesc_t +
                sizeof(ttXlaUpdateDesc_t);
char *newRow = oldRow + ttXlaUpdateDesc_t.tuple1;

See "ttXlaColDesc_t" for details on how to access the column data in a returned row.


ttXlaStatus_t

The ttXlaStatus_t structure shows runtime operational information about the XLA system. This structure is returned by the ttXlaStatus function when operating XLA in non-persistent mode.

Field Type Description
header ttXlaNodeHdr_t Standard data header.
xlabuffree SQLUBIGINT Free bytes in the staging buffer.
xlabufminfree SQLUBIGINT Minimum free bytes in the staging buffer.
xlabufalloc SQLUBIGINT Allocated bytes in the staging buffer.
xlabuftran SQLUBIGINT Number of transactions in the staging buffer.
xlabufrec SQLUBIGINT Number of records in the staging buffer.
logbuffree SQLUBIGINT Number of free bytes in the transaction log buffer.
logbufminfree SQLUBIGINT Minimum free bytes in the transaction log buffer.
logbufalloc SQLUBIGINT Number of allocated bytes in the transaction log buffer.
flags SQLUINTEGER A bit map of status flags. Currently, only the TTXLASTAT_STALLED flag is defined. If set, this flag specifies that the XLA staging buffer is full and new updates are being rejected.


ttXlaVersion_t

To permit future extensions to XLA, a version structure ttXlaVersion_t describes the current XLA version and structure byte order. This structure is returned by the ttXlaGetVersion function.

This structure includes the following fields:

Field Type Description
header ttXlaNodeHdr_t Standard data header.
hardware char (16) Name of hardware platform.
wordSize SQLUINTEGER Native word size (32 or 64).
TTMajor SQLUINTEGER TimesTen major version.
TTMinor SQLUINTEGER TimesTen minor version.
TTPatch SQLUINTEGER TimesTen point release number.
OS char (16) Name of operating system.
OSMajor SQLUINTEGER Operating system major version.
OSMinor SQLUINTEGER Operating system minor version.


ttXlaTblDesc_t

Table information is portrayed through the ttXlaTblDesc_t structure. This structure is returned by the ttXlaGetTableInfo function.

This structure includes the following fields:

Field Type Description
header ttXlaNodeHdr_t Standard data header.
tblName char (31) Name of the table, null-terminated.
tblOwner char (31) Owner of the table, null-terminated.
sysTableID SQLUBIGINT Unique system-defined table identifier.
userTableId SQLUBIGINT User-defined table identifier.
columns SQLUINTEGER Number of columns.
width SQLUINTEGER Inline row size.
nPrimCols SQLUINTEGER Number of primary columns.
primColsSys SQLUINTEGER(16) System primary key column numbers.
primColsUser SQLUINTEGER(16) User-defined primary key column numbers.

The inline row size includes space for all fixed-width columns, null column flags, and pointer information for variable-length columns. Each varying-length column occupies 4 bytes of inline row space.

Note the following if the table has a declared primary key:


ttXlaTblVerDesc_t

This data structure contains the table version number and ttXlaTblDesc_t. It is returned by ttXlaVersionTableInfo. This structure includes the following fields:

Field Type Description
tblDesc ttXlaTblDesc_t Table description.
tblVer SQLBIGINT System-generated table version number.


ttXlaColDesc_t

Column information is given through the ttXlaColDesc_t structure. This structure is returned by the ttXlaGetColumnInfo function.

This structure includes the following fields:

Field Type Description
header ttXlaNodeHdr_t Standard data header.
colName [tt_NameLenMax] char Name of the column.
pad0 SQLUINTEGER Pad to 4-byte boundary.
sysColNum SQLUINTEGER Column number, numbered from 1.
userColNum SQLUINTEGER User-assigned column number.
dataType SQLUINTEGER Structure in ODBC TTXLA_* code.

See "About XLA data types".

size SQLUINTEGER Max or basic size of column.
offset SQLUINTEGER Offset to fixed-length part of column.
nullOffset SQLUINTEGER Offset to null byte; zero if not nullable.
precision SQLSMALLINT Numeric precision for decimal types.
scale SQLSMALLINT Numeric scale for decimal types.
flags SQLUINTEGER Column flag:
  • TT_COLPRIMKEY - Column is primary key.

  • TT_COLVARYING - Column is stored out of line.

  • TT_COLNULLABLE - Column is nullable.

  • TT_COLUNIQUE - Column has a unique attribute defined on it.


The procedures for obtaining a ttXlaColDesc_t structure and inspecting its contents are described in "Inspecting column data". Below is a summary of these procedures.

The ttXlaColDesc_t structure is returned by the ttXlaGetColumnInfo function. This structure contains the metadata needed to access column information in a particular table. For example, you can use the offset field to locate specific column data in the row or rows returned in an update record after the ttXlaColDesc_t structure. By adding the offset to the address of a returned row, you can locate the address to the column value. You can then cast this value to the corresponding C types according to the dataType field, or pass it to one of the conversion routines described in "Converting complex data types".

TimesTen row data consists of fixed-length data followed by any variable-length data.

For columns that can have null values, nullOffset points to a null byte in the record. This value is 1 if the column is null, or 0 if it is not null. See "Detecting null values" for a discussion.

The flags bits define whether the column is nullable, part of a primary key, or stored out of line.

The sysColNum value is the system column number to assign to the column. This value begins with 1 for the first column.

Example 9-1 Copying and printing a VARCHAR string

For fixed-length column data, the address of a column is the offset value in the ttXlaColDesc_t structure, plus the address of the row as follows:

ttXlaColDesc_t colDesc;

void* pColVal = colDesc->offset + row;

The value of the column can be obtained by dereferencing this pointer using a type pointer that corresponds to the data type. For example, in the case of SQL_INTEGER, the ODBC type is SQLINTEGER and the value of the column can be obtained by the following:

*((SQLINTEGER*) pColVal))

In the case of variable-length column data, the pColVal calculated above is the address of a 4-byte offset value. Adding this offset value to the address of pColVal provides a pointer to the beginning of the variable-length column data. Assuming the operation is performed on a 64-bit platform, the first 8 bytes at this location is the length of this data (var_len), followed by the actual data (var_data).

In this example, a VARCHAR string is copied and printed.

tt_ptrint* var_len = (tt_ptrint*)((char*)pColVal +
                    *((int*)pColVal));
char* var_data = (char*)(var_len+1);
char *buffer = malloc(*var_len+1);
memcpy(buffer,var_data,*var_len);
buffer[*var_len] = (char)NULL; /* NULL terminate the string */
printf("%s\n",buffer);
free(buffer);

tt_LSN_t

Description of log record identifier used by bookmarks. This structure is used by the ttXlaUpdateDesc_t structure.

Field Type Description
logFile SQLUBIGINT Higher order portion of log record identifier.
logOffset SQLUBIGINT Lower order portion of log record identifier.

Note:

The logFile and logOffset field names are retained for backward compatibility, although their usage has changed. In previous releases the values referred to LSNs, which increased sequentially, and the values had very specific meanings, indicating the log file number plus byte offset. Now they refer to log record identifiers, which are more abstract and do not have a direct relationship to the log file number and byte offset. All you can assume about a sequence of log record identifiers is that a log record identifier B read at a later time than a log record identifier A will have a higher value.

tt_XlaLsn_t

Description of a log record identifier used by bookmarks. This structure is returned by the ttXlaGetLSN function and used by the ttXlaSetLSN function.

The checksum is specific to an XLA handle to ensure that every log record identifier is related to a known XLA connection.

Field Type Description
checksum SQLUINTEGER Checksum used to ensure that it is a valid log record identifier handle.
xid SQLUSMALLINT Transaction ID.
logFile SQLUBIGINT Higher order portion of log record identifier.
logOffset SQLUBIGINT Lower order portion of log record identifier.

Note:

The logFile and logOffset field names are retained for backward compatibility, although their usage has changed. In previous releases the values referred to LSNs, which increased sequentially, and the values had very specific meanings, indicating the log file number plus byte offset. Now they refer to log record identifiers, which are more abstract and do not have a direct relationship to the log file number and byte offset. All you can assume about a sequence of log record identifiers is that a log record identifier B read at a later time than a log record identifier A will have a higher value.