XLA Function Reference

This section provides reference information for XLA core functions and XLA data type conversion functions.

The functions are listed in alphabetical order.

Note:

Functions used exclusively for XLA as a replication mechanism are documented in a separate section, XLA Replication Function Reference.

ttXlaAcknowledge

Description

This function is used 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.

Note:

• 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 if there are no 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.

Required Privilege

XLA

Syntax

SQLRETURN ttXlaAcknowledge(ttXlaHandle_h handle)

Parameters

Parameter	Type	Description
handle	ttXlaHandle_h	Transaction log handle

Returns

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

Example

rc = ttXlaAcknowledge(xlahandle);

See Also

• ttXlaNextUpdate
• ttXlaNextUpdateWait

ttXlaClose

Description

Closes an XLA handle that was opened by ttXlaPersistOpen. See Terminating an XLA Application.

Required Privilege

XLA

Syntax

SQLRETURN ttXlaClose(ttXlaHandle_h handle)

Parameters

Parameter	Type	Description
handle	ttXlaHandle_h	ODBC handle for the database

Returns

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 following call:

rc = ttXlaClose(xlahandle);

See Also

• ttXlaPersistOpen

ttXlaConvertCharType

Description

Converts the column data indicated by the colinfo and tup parameters into the connection character set associated with the transaction log handle and places the result in a buffer.

Required 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	Transaction log handle for the database
colinfo	ttXlaColDesc_t*	Pointer to the buffer that holds the column descriptions
tup	void*	Data 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

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.

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

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	DATE_STRUCT*	Pointer to storage allocated to hold the converted date

Returns

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

ttXlaDecimalToCString

Converts a TTXLA_DECIMAL_TT value to a string usable by applications.

Description

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 equals 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.

Required 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	char*	Pointer to storage allocated to hold the converted string
precision	SQLSMALLINT	If fromData is greater than 1, the maximum number of digits before and after the decimal point If fromData is less than 1, same as scale
scale	SQLSMALLINT	Maximum number of digits after the decimal point

Returns

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 transaction log 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 database handle and the effect is the same as having opened the 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.

Note:

• 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

XLA

Syntax

SQLRETURN ttXlaDeleteBookmark(ttXlaHandle_h handle)

Parameters

Parameter	Type	Description
handle	ttXlaHandle_h	Transaction log handle

Returns

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 any errors encountered from the previous call on the given transaction log 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 "XLA Error Handling" for a discussion about using this function.

Required 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	Transaction log handle for the database
errCode	SQLINTEGER*	Code of the error message to be copied into the errMessage buffer
errMessage	char*	Buffer to hold the error text
maxLen	SQLINTEGER	Maximum length of the errMessage buffer
retLen	SQLINTEGER*	Actual size of the error message

Returns

Returns SQL_SUCCESS if error information is returned, or 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.

Note:

SQL_NO_DATA_FOUND is defined in sqlext.h, which is included by timesten.h.

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 XLA Error Handling.

Required Privilege

XLA

Syntax

SQLRETURN ttXlaErrorRestart(ttXlaHandle_h handle)

Parameters

Parameter	Type	Description
handle	ttXlaHandle_h	Transaction log handle for the database

Returns

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

Example

rc = ttXlaErrorRestart(xlahandle);

See Also

ttXlaError

ttXlaGetColumnInfo

Description

Retrieves information about all the columns in the table. The output parameter for number of columns returned, 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 definition.

See Obtaining Column Descriptions.

Required 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	Transaction log handle for the database
systemTableID	SQLUBIGINT	System ID of table
userTableID	SQLUBIGINT	User ID of table
colinfo	ttXlaColDesc_t*	Pointer to the buffer large enough to hold a separate description for maxcols columns
maxcols	SQLINTEGER	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	SQLINTEGER*	Number of columns returned

Returns

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 the transaction log handle. See How Bookmarks Work.

Required Privilege

XLA

Syntax

SQLRETURN ttXlaGetLSN(ttXlaHandle_h handle,
                      out tt_XlaLsn_t* LSN)

Parameters

Parameter	Type	Description
handle	ttXlaHandle_h	Transaction log handle for the database
LSN	tt_XlaLsn_t*	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

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 (refer to the description of the ttXlaTblDesc_t data type.) If the userTableID parameter 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

XLA

Syntax

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

Parameters

Parameter	Type	Description
handle	ttXlaHandle_h	Transaction log handle for the database
systemTableID	SQLUBIGINT	System table ID
userTableID	SQLUBIGINT	User table ID
tblinfo	ttXlaTblDesc_t*	Row information

Returns

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 following 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.

The function 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.

Required Privilege

XLA

Syntax

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

Parameters

Parameter	Type	Description
handle	ttXlaHandle_h	Transaction log handle for the database
configuredVersion	ttXlaVersion_t*	Configured version of XLA
actualVersion	ttXlaVersion_t*	Actual version of XLA

Returns

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 following call:

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

See Also

• ttXlaVersionCompare
• ttXlaSetVersion

ttXlaNextUpdate

Description

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

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.

Required Privilege

XLA

Syntax

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

Parameters

Parameter	Type	Description
handle	ttXlaHandle_h	Transaction log handle for the database
records	ttXlaUpdateDesc_t***	Buffer to hold the completed transaction records
maxrecords	SQLINTEGER	Maximum number of records to be fetched
nreturned	SQLINTEGER*	Actual number of returned records, where 0 is returned if no update data is available

Returns

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 the tracking status of a table.

See Also

• ttXlaNextUpdateWait
• ttXlaAcknowledge

ttXlaNextUpdateWait

Description

This is 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

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	Transaction log handle for the database
records	ttXlaUpdateDesc_t***	Buffer to hold completed transaction records
maxrecords	SQLINTEGER	Maximum number of records to be fetched Note: The largest effective value is 1000 records.
nreturned	SQLINTEGER*	Actual number of records returned, where 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

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

Example

This example retrieves up to 100 records and waits 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

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

Returns SQL_SUCCESS if call is successful. Otherwise, use ttXlaError to report the 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

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*	Number of bytes that were written, assuming buflen is large enough (otherwise, the number of bytes that would have been written)

Returns

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

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

Returns SQL_SUCCESS if call is successful. Otherwise, use ttXlaError to report the 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

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

Returns SQL_SUCCESS if call is successful. Otherwise, use ttXlaError to report the 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

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

Returns SQL_SUCCESS if call is successful. Otherwise, use ttXlaError to report the 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

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

Returns SQL_SUCCESS if call is successful. Otherwise, use ttXlaError to report the 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

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

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

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

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*	ODBC timestamp value converted from the XLA Oracle Database DATE value

Returns

Returns SQL_SUCCESS if call is successful. Otherwise, use ttXlaError to report the 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

XLA

Parameters

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

Returns

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

ttXlaPersistOpen

Description

Initializes a transaction log handle to a database to enable access to the transaction log. The hdbc parameter is an ODBC connection handle to a database. 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 XLA bookmark (see About XLA Bookmarks). The tag can identify a new bookmark, either non-replicated or replicated, or one that 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:

• ttXlaAcknowledge

• ttXlaGetLSN

• ttXlaSetLSN

• ttXlaNextUpdate

• ttXlaNextUpdateWait

Multiple applications can concurrently read from the transaction log. See Initializing XLA and Obtaining an XLA Handle.

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.

Note:

Space is allocated by this call. Call ttXlaClose to free space when you are finished.

Required Privilege

XLA

Syntax

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

Parameters

Parameter	Type	Description
hdbc	SQLHDBC	ODBC handle for the database
tag	SQLCHAR*	Identifier for the XLA bookmark This 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	ttXlaHandle_h*	Transaction log handle returned by this call

Returns

Returns SQL_SUCCESS or SQL_SUCCESS_WITH_INFO if call is successful. Otherwise, call SQLError on the HDBC connection handle that was passed in as an argument.

Example

This example opens a transaction log, 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

ttXlaRowidToCString

Description

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

Required 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

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 database specified by the transaction 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 Initial Read log record identifier.

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

Required Privilege

XLA

Syntax

SQLRETURN ttXlaSetLSN(ttXlaHandle_h handle,
                      tt_XlaLsn_t* LSN)

Parameters

Parameter	Type	Description
handle	ttXlaHandle_h	Transaction log handle for the database
LSN	tt_XlaLsn_t*	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

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.

Required Privilege

XLA

Syntax

SQLRETURN ttXlaSetVersion(ttXlaHandle_h handle,
                          ttXlaVersion_t* version)

Parameters

Parameter	Type	Description
handle	ttXlaHandle_h	Transaction log handle for the database
version	ttXlaVersion_t*	Desired version of XLA

Returns

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 following call:

rc = ttXlaSetVersion(xlahandle, &requestedVersion);

See Also

• ttXlaVersionCompare
• ttXlaGetVersion

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.

Required 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	Transaction log handle for the database
owner	char*	Owner for the table or view as a string
name	char*	Name of the table or view
sysTableID	SQLUBIGINT*	System table ID
userTableID	SQLUBIGINT*	User table ID

Returns

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

Example

To get the system and user table IDs associated with the table PURCHASING.INVOICES, use the following call:

SQLUBIGINT sysTableID;
SQLUBIGINT userTableID;

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

See Also

ttXlaTableStatus

ttXlaTableStatus

Description

Returns the update status for a table. 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. The function 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, CREATSYN, DROPSYN, ADDCOLS, DRPCOLS, TRUNCATE, SETTBL1, and SETCOL1 transactions. See ttXlaUpdateDesc_t.

See "Specifying Which Tables to Monitor for Updates" for a discussion about using this function.

Note:

DML updates to a table being tracked through XLA do not prevent ttXlaTableStatus from running. However, DDL updates to the table being tracked, which take a lock on SYS.TABLES, do delay ttXlaTableStatus from running in serializable isolation against SYS.TABLES.

Required Privilege

XLA

Syntax

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

Parameters

Parameter	Type	Description
handle	ttXlaHandle_h	Transaction log handle for the database
systemTableID	SQLUBIGINT	System ID of table
userTableID	SQLUBIGINT	User ID of table
oldstatus	SQLINTEGER*	XLA old status: 1: On 0: Off
newstatus	SQLINTEGER*	XLA new status: 1: On 0: Off

Returns

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 following call:

/* Get system table identifier into systemTableID, then ... */
rc = ttXlaTableStatus(xlahandle, systemTableID, 0,
                      &currentStatus, NULL);

The currentStatus value is 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 the following 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 through 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

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

XLA

Syntax

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

Parameters

Parameter	Type	Description
handle	ttXlaHandle_h	Transaction log handle for the database
table	ttXlaTblVerDesc_t*	A cached table description
record	ttXlaUpdateDesc_t*	XLA record to be processed
compat	SQLINTEGER*	Compatibility information: 1: Tables are compatible. 0: Tables are not compatible.

Returns

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

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

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

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	TIME_STRUCT*	Pointer to storage allocated to hold the converted time

Returns

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

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	TIMESTAMP_STRUCT*	Pointer to storage allocated to hold the converted timestamp

Returns

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 timestamp value, pColVal, from a row returned in a transaction log record.

TIMESTAMP_STRUCT timestamp;

rc = ttXlaTimeStampToODBCCType(pColVal, &timestamp);

ttXlaVersionColumnInfo

Description

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

Required privilege

XLA

Syntax

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

Parameters

Parameter	Type	Description
handle	ttXlaHandle_h	Transaction log handle for the database
record	ttXlaUpdateDesc_t*	XLA record to be processed
colinfo	ttXlaColDesc_t*	A pointer to the buffer large enough to hold a description for maxcols columns
maxcols	SQLINTEGER	Maximum number of columns the table can have Note: If the table contains more than maxcols columns, an error is returned.
nreturned	SQLINTEGER*	Number of columns returned

Returns

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

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 a result indicating either that the versions are the same, or which version is earlier.

Required Privilege

XLA

Syntax

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

Parameters

Parameter	Type	Description
handle	ttXlaHandle_h	Transaction log handle for the database
version1	ttXlaVersion_t*	Version of XLA to compare with version2
version2	ttXlaVersion_t*	Version of XLA to compare with version1
comparison	SQLINTEGER*	Comparison result: 0: Indicates version1 and version2 match. -1: Indicates version1 is earlier than version2. +1: Indicates version1 is later than version2.

Returns

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 the following 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, use 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

XLA

Syntax

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

Parameters

Parameter	Type	Description
handle	ttXlaHandle_h	Transaction log handle for the database
record	ttXlaUpdateDesc_t*	XLA record to be processed
tableinfo	ttXlaTblVerDesc_t*	Information about table definition

Returns

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

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);