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:
installation_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 |
---|---|
Describes the record type. Used at the beginning of records returned by XLA. |
|
Describes an update record. |
|
Describes XLA version information returned by |
|
Describes table information returned by |
|
Describes table version returned by |
|
Describes table column information returned by |
|
Describes a log record identifier used by bookmarks. This structure is used by the |
|
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 has the following fields.
Field | Type | Description |
---|---|---|
|
|
The type of record:
|
|
|
Byte order of the record:
|
|
|
Total length of record, including all attachments |
ttXlaUpdateDesc_t
This structure describes an update operation to a single row (or tuple) in the database.
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 database. The row data differs depending on the record type reported in the ttXlaUpdateDesc_t
header:
-
No rows are present in a
COMMITONLY
record. -
One row is present in
INSERTTUP
orDELETETUP
. -
Two rows are present in an
UPDATETUP
record to report the row data before and after the update, respectively. -
Special format rows are present in
CREATAB
,DROPTAB
,CREAIND
,DROPIND
,CREATVIEW
,DROPVIEW
,CREATSEQ
,DROPSEQ
,CREATSYN
,DROPSYN
,ADDCOLS
, andDRPCOLS
records, which are described in Special Update Data Formats.
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 following:
-
CREATE VIEW
orDROP VIEW
for a non-materialized view -
CREATE GLOBAL TEMPORARY TABLE
orDROP TABLE
for a temporary table
The only XLA records that can be generated from an ALTER TABLE
operation are of the following types:
-
ADDCOLS
orDRPCOLS
when columns are added or dropped -
CREAIND
orDROPIND
when a unique attribute of a column is modified
While sequence creates (CREATESEQ
) and drops (DROPSEQ
) are visible through XLA, sequence increments are not.
All deletes resulting from cascading deletes and 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.
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. See ttXlaTblDesc_t.
CREATE TABLE
For a CREATE TABLE
operation, the special row value consists of the ttXlaTblDesc_t
record describing the new table, followed by the ttXlaColDesc_t
records that describe each column.
See ttXlaColDesc_t.
ALTER TABLE
For an ALTER TABLE
operation, 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 |
---|---|---|
|
|
Name of the dropped table |
|
|
Owner of the dropped table |
ttXlaTruncateTableTup_t
For a TRUNCATE TABLE
operation, the row value is as follows.
Field | Type | Description |
---|---|---|
|
|
Name of the truncated table |
|
|
Owner of the truncated table |
ttXlaCreateIndexTup_t
For a CREATE INDEX
operation, the row value is as follows.
Field | Type | Description |
---|---|---|
|
|
Name of the table on which the index is defined |
|
|
Owner of the table on which the index is defined |
|
|
Name of the new index |
|
|
Index flag:
|
|
|
Number of indexed columns |
|
|
Indexed column numbers using system numbers |
|
|
Indexed column numbers using user-defined column IDs |
|
|
Type of index:
|
|
|
Uniqueness of index:
|
|
|
Number of pages for hash indexes |
ttXlaDropIndexTup_t
For a DROP INDEX
operation, the row value is as follows.
Field | Type | Description |
---|---|---|
|
|
Name of the table on which the index was dropped |
|
|
Owner of the table on which the index was dropped |
|
|
Name of the dropped index |
ttXlaAddColumnTup_t
For an ADD COLUMN
operation, the row value is as follows.
Field | Type | Description |
---|---|---|
|
|
Number of additional columns |
Following this special row are the ttXlaColDesc_t
records describing the new columns.
ttXlaDropColumnTup_t
For a DROP COLUMN
operation, the row value is as follows.
Field | Type | Description |
---|---|---|
|
|
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 |
---|---|---|
|
|
Name of sequence |
|
|
Owner of sequence |
|
|
Cycle flag Indicates whether the sequence number generator continues to generate numbers after it reaches the maximum or minimum value:
|
|
|
Minimum value of sequence |
|
|
Maximum value of sequence |
|
|
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 |
ttXlaDropSeqTup_t
For a DROP SEQUENCE
operation, the row value is as follows.
Field | Type | Description |
---|---|---|
|
|
Name of sequence |
|
|
Owner of sequence |
ttXlaViewDesc_t
For a CREATE VIEW
operation, the row value is as follows.
Note:
This applies to either materialized or non-materialized views.
Field | Type | Description |
---|---|---|
|
|
Name of view |
|
|
Owner of view |
|
|
System table ID stored in |
ttXlaDropViewTup_t
For a DROP VIEW
operation, the row value is as follows.
Note:
This applies to either materialized or non-materialized views.
Field | Type | Description |
---|---|---|
|
|
Name of view |
|
|
Owner of view |
ttXlaCreateSynTup_t
For a CREATE SYNONYM
operation, the row value is as follows.
Field | Type | Description |
---|---|---|
|
|
Name of synonym |
|
|
Owner of synonym |
|
|
Name of object the synonym points to |
|
|
Owner of object the synonym points to |
|
|
Indicates whether the synonym is public:
|
|
|
Indicates whether the synonym was created using
|
ttXlaDropSynTup_t
For a DROP SYNONYM
operation, the row value is as follows.
Field | Type | Description |
---|---|---|
|
|
Name of synonym |
|
|
Owner of synonym |
|
|
Indicates whether the synonym is public:
|
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 |
---|---|---|
|
|
New user-defined table ID |
ttXlaSetColumnTup_t
The description of the SET COLUMN ID
operation provides the following special row:
Field | Type | Description |
---|---|---|
|
|
Previous user-defined column ID value |
|
|
New user-defined column ID value |
|
|
System column ID |
Locating the Row Data Following a ttXlaUpdateDesc_t Header
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.
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.
See 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.
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 has the following fields:
Field | Type | Description |
---|---|---|
|
Standard data header |
|
|
|
Name of hardware platform |
|
|
Native word size (32 or 64 bits) |
|
|
TimesTen major version |
|
|
TimesTen minor version |
|
|
TimesTen point release number |
|
|
Name of operating system |
|
|
Operating system major version |
|
|
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 has the following fields:
Field | Type | Description |
---|---|---|
|
Standard data header |
|
|
|
Name of the table, null-terminated |
|
|
Owner of the table, null-terminated |
|
|
Unique system-defined table identifier |
|
|
User-defined table identifier |
|
|
Number of columns |
|
|
Inline row size |
|
|
Number of primary columns |
|
|
System primary key column numbers |
|
|
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 four bytes of inline row space.
Note the following if the table has a declared primary key:
-
The
nPrimCols
value is greater than 0. -
The
primColsSys
array contains the column numbers of the primary key, in the same order in which they were originally declared with theCREATE TABLE
statement. -
The
primColsUser
array contains the corresponding application-specified column identifiers.
ttXlaTblVerDesc_t
This data structure contains the table version number and ttXlaTblDesc_t
.
It is returned by ttXlaVersionTableInfo
. This structure has the following fields:
Field | Type | Description |
---|---|---|
|
Table description |
|
|
|
System-generated table version number |
ttXlaColDesc_t
Column information is given through this structure, which is returned by the ttXlaGetColumnInfo
function.
The structure has the following fields:
Field | Type | Description |
---|---|---|
|
Standard data header |
|
|
|
Name of the column |
|
|
Pad to four-byte boundary |
|
|
Ordinal number of the column as determined when the table is created or subsequently altered This is the same as the corresponding |
|
|
Ordinal number of the column if optionally specified by the user This is zero or a column number specified through the |
|
|
Structure in See XLA Data Types. |
|
|
Maximum or basic size of column |
|
|
Offset to fixed-length part of column |
|
|
Offset to null byte, or zero if not nullable |
|
|
Numeric precision for decimal types |
|
|
Numeric scale for decimal types |
|
|
Column flag:
|
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 fixed length column data,
ttXlaColDesc_t
returns theoffset
andsize
of the column data. Theoffset
is relative to the beginning of the fixed part of the record. See the example below. -
For variable-length column data (
VARCHAR2
,NVARCHAR2
, andVARBINARY
),offset
is an address that points to a four-byte offset value. By adding the offset address to the offset value, you can obtain the address of the column data in the variable-length portion of the row. The first eight bytes at this location is the length of the data, followed by the actual data. For variable-length data, the returned size value is the maximum allowable column size. See the example below.
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.
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.
Note:
LOB support in XLA is limited, as follows:
-
You can subscribe to tables containing LOB columns, but information about the LOB value itself is unavailable.
-
ttXlaGetColumnInfo
returns information about LOB columns. -
Columns containing LOBs are reported as empty (zero length) or null (if the value is actually
NULL
). In this way, you can tell the difference between a null column and a non-null column.
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, for 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 four-byte offset value. Adding this offset value to the address of pColVal
provides a pointer to the beginning of the variable-length column data. The first eight 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 |
---|---|---|
|
|
Higher order portion of log record identifier |
|
|
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 has 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 used to ensure that it is a valid log record identifier handle |
|
|
Transaction ID |
|
|
Higher order portion of log record identifier |
|
|
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 has a higher value.