1. C Developer's Guide
  2. XLA Reference
  3. C Data Structures Used by XLA

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

ttXlaNodeHdr_t

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

ttXlaUpdateDesc_t

Describes an update record.

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

Describes 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 has the following 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 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 or DELETETUP.

  • 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, and DRPCOLS 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 or DROP VIEW for a non-materialized view

  • CREATE GLOBAL TEMPORARY TABLE or DROP TABLE for a temporary table

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

  • ADDCOLS or DRPCOLS when columns are added or dropped

  • CREAIND or DROPIND 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.

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.

  • CREATSYN: Create synonym.

  • DROPSYN: Drop synonym.

  • ADDCOLS: Add columns.

  • DRPCOLS: Drop columns.

  • 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 database.

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

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 key

  • "F": Foreign key

  • "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

Type of index:

  • "T": Range

  • "H": Hash

  • "B": Bit map

ixUnique

char

Uniqueness of index:

  • "U": Unique

  • "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 an ADD COLUMN operation, the row value is as follows.

Field Type Description

ncols

SQLUINTEGER

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

ncols

SQLUINTEGER

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

Cycle flag

Indicates whether the sequence number generator continues to generate numbers after it reaches the maximum or minimum value:

  • "1": Yes

  • "0": No

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 VIEW operation, the row value is as follows.

Note:

This applies to either materialized or non-materialized views.

Field Type Description

vwName

char(31)

Name of view

vwOwner

char(31)

Owner of view

sysTableID

SQLUBIGINT

System table ID stored in SYS.TABLES
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

vwName

char(31)

Name of view

vwOwner

char(31)

Owner of view
ttXlaCreateSynTup_t

For a CREATE SYNONYM operation, the row value is as follows.

Field Type Description

synName

char(31)

Name of synonym

synOwner

char(31)

Owner of synonym

objName

char(31)

Name of object the synonym points to

objOwner

char(31)

Owner of object the synonym points to

isPublic

char

Indicates whether the synonym is public:

  • "1": True

  • "0": False

isReplace

char

Indicates whether the synonym was created using CREATE OR REPLACE:

  • "1": True

  • "0": False
ttXlaDropSynTup_t

For a DROP SYNONYM operation, the row value is as follows.

Field Type Description

synName

char(31)

Name of synonym

synOwner

char(31)

Owner of synonym

isPublic

char

Indicates whether the synonym is public:

  • "1": True

  • "0": False
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

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

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

header

ttXlaNodeHdr_t

Standard data header

hardware

char(16)

Name of hardware platform

wordSize

SQLUINTEGER

Native word size (32 or 64 bits)

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 has 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 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 the CREATE 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

tblDesc

ttXlaTblDesc_t

Table description

tblVer

SQLBIGINT

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

header

ttXlaNodeHdr_t

Standard data header

colName [tt_NameLenMax]

char

Name of the column

pad0

SQLUINTEGER

Pad to four-byte boundary

sysColNum

SQLUINTEGER

Ordinal number of the column as determined when the table is created or subsequently altered

This is the same as the corresponding COLNUM value in SYS.COLUMNS. (See SYS.COLUMNS in Oracle TimesTen In-Memory Database System Tables and Views Reference.)

userColNum

SQLUINTEGER

Ordinal number of the column if optionally specified by the user

This is zero or a column number specified through the ttSetUserColumnID TimesTen built-in procedure. (See ttSetUserColumnID in Oracle TimesTen In-Memory Database Reference.)

dataType

SQLUINTEGER

Structure in ODBC TTXLA_* code

See XLA Data Types.

size

SQLUINTEGER

Maximum or basic size of column

offset

SQLUINTEGER

Offset to fixed-length part of column

nullOffset

SQLUINTEGER

Offset to null byte, or 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 fixed length column data, ttXlaColDesc_t returns the offset and size of the column data. The offset is relative to the beginning of the fixed part of the record. See the example below.

  • For variable-length column data (VARCHAR2, NVARCHAR2, and VARBINARY), 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

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

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 has a higher value.