XLA Replication Function Reference
This section documents the functions that are exclusive to using XLA as a replication mechanism. Functions are listed in alphabetical order.
ttXlaApply
This function is part of XLA replication functionality and is not appropriate for use in a typical XLA application.
Description
Applies an update to the database associated with the transaction log 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 database transaction is committed. No other transaction commits are performed by ttXlaApply. If the parameter test (see syntax below) is true, the "old values" in the update description are compared against the current contents of the database for record updates and deletions. If the old value in the update description does not match the corresponding row in the database, this function rejects the update and returns an sb_ErrXlaTupleMismatch error.
See Using XLA as a Replication Mechanism.
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
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 |
|---|---|---|
|
|
|
Transaction log handle for the database |
|
|
|
Transaction to generate SQL statement |
|
|
|
Test for old values:
|
Returns
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 database 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.
ttXlaCommit
This function is part of XLA replication functionality and is not appropriate for use in a typical XLA application.
Description
Commits the current transaction being applied on the transaction log 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, which applies the current transaction if it does not encounter an error.
Required Privilege
XLA
Syntax
SQLRETURN ttXlaCommit(ttXlaHandle_h handle)Parameters
| Parameter | Type | Description |
|---|---|---|
|
|
|
Transaction log handle for the database |
Returns
Returns SQL_SUCCESS if call is successful. Otherwise, use ttXlaError to report the error.
Example
rc = ttXlaCommit(xlahandle);
ttXlaGenerateSQL
This function is part of XLA replication functionality and is not appropriate for use in a typical XLA application.
Note:
This function does not currently work with LOB locators.
Description
Generates a SQL DML or DDL statement that expresses the effect of the update record. The generated statement is not applied to any 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.
Required Privilege
XLA
Syntax
SQLRETURN ttXlaGenerateSQL(ttXlaHandle_h handle,
ttXlaUpdateDesc_t* record,
out char* buffer,
SQLINTEGER maxLen,
out SQLINTEGER* actualLen)Parameters
| Parameter | Type | Description |
|---|---|---|
|
|
|
Transaction log handle for the database |
|
|
Record to be translated into SQL |
|
|
|
|
Location of the translated SQL statement |
|
|
|
Maximum length of the buffer, in bytes |
|
|
|
Actual length of the buffer, in bytes |
Returns
Returns SQL_SUCCESS if call is successful. Otherwise, use ttXlaError to report the error.
Example
This example generates the text of a 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.
ttXlaLookup
This function is part of XLA replication functionality and is not appropriate for use in a typical XLA application.
Description
This function looks for a record in the given table with key values according to the keys parameter. The formats of the keys and result records are the same as for ordinary rows. This function requires a primary key on the underlying table.
Required 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 |
|---|---|---|
|
|
|
Transaction log handle for the database |
|
|
Table to search |
|
|
|
|
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. |
|
|
|
Where the located record is copied If no record exists with the matching key columns, an error is returned. |
|
|
|
Size of the largest record that can fit into the result buffer |
|
|
|
Actual size of the record |
Returns
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);ttXlaRollback
This function is part of XLA replication functionality and is not appropriate for use in a typical XLA application.
Description
Rolls back the current transaction being applied on the transaction log handle. You can call this routine to respond to transient errors (timeout or deadlock) reported by ttXlaApply.
Required Privilege
XLA
Syntax
SQLRETURN ttXlaRollback(ttXlaHandle_h handle)Parameters
| Parameter | Type | Description |
|---|---|---|
|
|
|
Transaction log handle for the database |
Returns
Returns SQL_SUCCESS if call is successful. Otherwise, use ttXlaError to report the error.
Example
rc = ttXlaRollback(xlahandle);
ttXlaTableCheck
This function is part of XLA replication functionality and is not appropriate for use in a typical XLA application.
Description
When using XLA as a replication mechanism, this function verifies that the named table in the ttXlaTblDesc_t structure received from a master database is compatible with a subscriber database or database associated with the transaction log handle. The compat parameter indicates whether the tables are compatible.
Required Privilege
XLA
Syntax
SQLRETURN ttXlaTableCheck(ttXlaHandle_h handle,
ttXlaTblDesc_t* table,
ttXlaColDesc_t* columns,
out SQLINTEGER* compat)Parameters
| Parameter | Type | Description |
|---|---|---|
|
|
|
Transaction log handle for the database |
|
|
Table description |
|
|
|
Column description for the table |
|
|
|
|
Compatibility information:
|
Returns
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
*/
}