9 XLAリファレンス

この章では、「XLAおよびTimesTenイベント管理」で説明したトランザクション・ログAPI（XLA）のリファレンス情報を示します。内容は次のとおりです。

• XLA関数について

• カテゴリ別のXLA関数の概要

• XLA関数リファレンス

• XLAで使用されるCデータ構造体

XLA関数について

この項には、XLA関数に関する情報が含まれています。

リターン・コードについて

この章で説明するすべてのXLA API関数は、SQLRETURN型の値を返します。この値は、ODBCによって次のいずれかの値になるように定義されています。

• SQL_SUCCESS

• SQL_SUCCESS_WITH_INFO

• SQL_NO_DATA_FOUND

• SQL_ERROR

XLAエラーの処理方法については、「XLAエラーの処理」を参照してください。

パラメータ・タイプ（入力、出力、入出力）について

関数の説明では、次のことに注意してください。

• 特に示されていないかぎり、すべてのパラメータは入力専用です。

• 出力パラメータにはOUTという接頭辞が付いています。

• 入出力パラメータにはIN OUTという接頭辞が付いています。

関数による出力結果について

このAPIのほとんどのルーチンは、結果をアプリケーション・バッファにコピーします。結果が含まれているバッファへのポインタを生成する一部のルーチンは、同じXLAハンドルを使用した次のコールが実行されるまでのみ有効性が保証されます。

このルールには次の例外があります。

• 診断情報を提供するttXlaError関数へのコール間では、バッファは有効なままです。

• ttXlaNextUpdateによって返された結果は、次にttXlaNextUpdate、ttXlaConfigBufferまたはttXlaAcknowledge（永続モード）をコールするまで有効なままです。 アプリケーションでバッファへのアクセスを長時間維持する必要がある場合は、XLAによって返されるバッファの情報をアプリケーション専用のバッファにコピーする必要があります。

実際の列値を除き、XLA内の文字列値はNULL文字で終了します。固定長のCHAR列は、その長さに合せて空白が埋め込まれます。VARCHAR列は、長さが明示的にエンコードされています。

XLAは、32ビットおよび64ビットの両方のプラットフォームに同じデータ構造を使用します。SQLUINTEGERおよびSQLUBIGINT型を使用して、32ビットおよび64ビットの整数が明示的に参照されます。 各SQLUINTEGER値が4バイト境界、各SQLUBIGINT値が8バイト境界に存在するように型定義に入力することによって、位置合せおよび埋込みの問題に対処します。 他のTimesTenデータ型の記憶域要件については、『Oracle TimesTen In-Memory Databaseオペレーション・ガイド』の行の理解に関する項を参照してください。

必要な権限について

XLA機能に対するTimesTenアクセス制御機能の影響については、「アクセス制御がXLAに与える影響」を参照してください。 XLA機能の実行には、システム権限XLAが必要になります。

カテゴリ別のXLA関数の概要

TimesTen XLAは、データ・ストアへの更新を検出するために使用したり、独自のレプリケーション・ソリューションを構築するツールキットとして使用できます（第5章「XLAおよびTimesTenイベント管理」を参照）。 XLAは、永続モードまたは非永続モードのいずれでも初期化できます。

この項では、XLA関数をその使用方法を基準に分類し、各関数について簡単に説明します。XLA関数には、次のカテゴリがあります。

• データ型変換関数を含むXLAコア関数

• XLA永続モード関数

• XLA非永続モード関数

• XLAレプリケーション関数

データ型変換関数を含むXLAコア関数

次の表に、すべてのXLAアプリケーションで使用可能なXLAコア関数を示します。

関数	説明
ttXlaClose	ttXlaPersistOpenによってオープンされたXLAハンドルをクローズします。
ttXlaConvertCharType	列データを接続キャラクタ・セットに変換します。
ttXlaError	エラー情報を取得します。
ttXlaErrorRestart	エラー・スタック情報をリセットします。
ttXlaGetColumnInfo	表内のすべての列に関する情報を取得します。
ttXlaGetTableInfo	表に関する情報を取得します。
ttXlaGetVersion	XLAの現行のバージョンを取得します。
ttXlaNextUpdate	TimesTenから一連の更新を取得します。
ttXlaNextUpdateWait	TimesTenから一連の更新を取得します。 使用可能な更新がトランザクション・ログにない場合は、指定した時間待機します。
ttXlaTableByName	所有者および名前が指定された表のシステム表識別子およびユーザー表識別子を検出します。
ttXlaTableStatus	表のXLAステータスを設定および取得します。
ttXlaSetVersion	使用するXLAのバージョンを設定します。
ttXlaTableVersionVerify	キャッシュされた表定義が、処理中のXLAレコードと互換性があること確認します。
ttXlaVersionColumnInfo	変更更新レコードの処理を必要とする表の列に関する情報を取得します。
ttXlaVersionCompare	2つのXLAバージョンを比較します。

これらの関数の使用方法については、「XLAイベント・ハンドラ・アプリケーションの作成」を参照してください。

次の表に、すべてのXLAアプリケーションで使用可能なデータ型変換関数を示します。

関数	説明
ttXlaDateToODBCCType	TTXLA_DATE_TT値を、アプリケーションで使用可能なODBC C値に変換します。
ttXlaDecimalToCString	TTXLA_DECIMAL_TT値を、アプリケーションで使用可能な文字列に変換します。
ttXlaNumberToBigInt	TTXLA_NUMBER値を、アプリケーションで使用可能なSQLBIGINT C値に変換します。
ttXlaNumberToCString	TTXLA_NUMBER値を、アプリケーションで使用可能なキャラクタ文字列に変換します。
ttXlaNumberToDouble	TTXLA_NUMBER値を、アプリケーションで使用可能な長い浮動小数点数値に変換します。
ttXlaNumberToInt	TTXLA_NUMBER値を、アプリケーションで使用可能な整数に変換します。
ttXlaNumberToSmallInt	TTXLA_NUMBER値を、アプリケーションで使用可能なSQLSMALLINT C値に変換します。
ttXlaNumberToTinyInt	TTXLA_NUMBER値を、アプリケーションで使用可能なSQLCHAR C値に変換します。
ttXlaNumberToUInt	TTXLA_NUMBER値を、アプリケーションで使用可能な符号なし整数に変換します。
ttXlaOraDateToODBCTimeStamp	TTXLA_DATE値を、アプリケーションで使用可能なODBCタイムスタンプに変換します。
ttXlaOraTimeStampToODBCTimeStamp	TTXLA_TIMESTAMP値を、アプリケーションで使用可能なODBCタイムスタンプに変換します。
ttXlaRowidToCString	ROWID値を、アプリケーションで使用可能なキャラクタ文字列値に変換します。
ttXlaTimeToODBCCType	TTXLA_TIME値を、アプリケーションで使用可能なODBC C値に変換します。
ttXlaTimeStampToODBCCType	TTXLA_TIMESTAMP_TT値を、アプリケーションで使用可能なODBC C値に変換します。

XLAデータ型の詳細は、「XLAデータ型について」を参照してください。

XLA永続モード関数

次の表に、永続モードのXLAのみを処理する関数を示します。

関数	説明
ttXlaPersistOpen	永続モードでトランザクション・ログにアクセスするためにTimesTenデータ・ストアへのハンドルを初期化します。
ttXlaAcknowledge	1つ以上のトランザクション更新レコードをトランザクション・ログから取得したことを確認します。
ttXlaDeleteBookmark	トランザクション・ログ・ブックマークを削除します。
ttXlaGetLSN	データ・ストアの現在のブックマークのログ・レコード識別子を取得します。
ttXlaSetLSN	データ・ストアの現在のブックマークのログ・レコード識別子を設定します。

これらの関数の使用方法については、「XLAイベント・ハンドラ・アプリケーションの作成」を参照してください。

XLA非永続モード関数

注意: TimesTenでは、永続モードでXLAを使用することをお薦めします。

次の表に、非永続モードのXLAのみを処理する関数を示します。

関数	説明
ttXlaOpenTimesTen	非永続モードでトランザクション・ログにアクセスするためにTimesTenデータ・ストアへのハンドルを初期化します。
ttXlaConfigBuffer	XLAステージング・バッファのサイズを設定します。
ttXlaStatus	現在のXLAステータスを取得します。
ttXlaResetStatus	XLAの統計カウンタをすべてリセットします。

XLAレプリケーション関数

次の表に、レプリケーション・メカニズムとしてXLAのみを使用する関数を示します。

関数	説明
ttXlaApply	XLAハンドルに関連付けられているデータ・ストアまたはデータベースに更新を適用します。
ttXlaTableCheck	送信側のデータ・ストアから受信した表記述内の指定した表が、受信側のデータ・ストアと互換性があることを検証します。
ttXlaLookup	特定のキー値を持つ表の更新レコードを検索します。
ttXlaRollback	トランザクションをロールバックします。
ttXlaCommit	トランザクションをコミットします。
ttXlaGenerateSQL	更新レコードの結果を示すSQL文を生成します。

これらの関数の使用方法については、「レプリケーション・メカニズムとしてのXLAの使用」を参照してください。

---

XLA関数リファレンス

この項では、各XLA関数のリファレンス情報を示します。関数は、アルファベット順に示されています。

---

ttXlaAcknowledge

説明

この関数は、1つ以上のレコードがttXlaNextUpdate関数またはttXlaNextUpdateWait関数によってトランザクション・ログから読み取られたことを確認するために、永続モードで使用します。

この関数をコールすると、以前に返されたいずれのレコードも再読取りできないようにブックマークが再設定されます。 ttXlaAcknowledgeは、メッセージが完全に処理された場合にのみコールします。

注意: ブックマークは、指定したハンドルに対してのみ再設定されます。 システム内の他のハンドルは、以前のトランザクションにアクセス可能な場合があります。 ブックマークは、確認する関連更新レコードがない場合でも再設定されます。

ttXlaAcknowledgeは、必要なときにのみ使用するようにする必要がある高コストの処理です。 トランザクション・ログ・ファイルを読み取るたびにttXlaAcknowledgeを複数回コールしても、トランザクション・ログのボリュームは減少しません。XLAではトランザクション・ログ・ファイルが一度に1つしかパージされないためです。 新しいトランザクション・ログ・ファイルの生成を検出するには、システム表SYS.TRANSACTION_LOG_APIのブックマークのpurgeLSN（PURGELSNHIGHとPURGELSNLOWの値で示される）を調べることで、ブックマークが含まれるログ・ファイルを確認できます。 その後、ttXlaAcknowledgeをコールして、古いトランザクション・ログ・ファイルをパージできます。 この表を表示するには、ADMINまたはSELECT ANY TABLE権限が必要です。

ttXlaAcknowledgeの2番目の目的は、XLAREUSEオプションが指定されたttXlaPersistOpen関数をコールして、以前使用されたブックマークに接続する場合に確認されたレコードがXLAアプリケーションで認識されないようにすることです。ブックマークを再利用する場合、ttXlaCloseをコールする前にttXlaAcknowledgeをコールしてブックマークの位置を現在のレコードに再設定します。

この関数の使用方法については、「トランザクション・ログからの更新レコードの取得」を参照してください。

必要な権限

システム権限XLAが必要です。

構文

SQLRETURN ttXlaAcknowledge(ttXlaHandle_h handle)

パラメータ

パラメータ	型	説明
handle	ttXlaHandle_h	トランザクション・ログ・ハンドル。

結果

コールが成功すると、SQL_SUCCESSが返されます。返されない場合は、ttXlaErrorを使用してエラーをレポートします。

例

rc = ttXlaAcknowledge(xlahandle);

参照

「ttXlaNextUpdate」
「ttXlaNextUpdateWait」

---

ttXlaApply

説明

handleに関連付けられているデータ・ストアまたはデータベースに更新を適用します。戻り値は、更新が成功したかどうかを示します。 また、更新によって永続的な問題が発生したかどうかも示します。 更新で一時的な問題（デッドロック、タイムアウトなど）が発生したかどうかを確認するには、ttXlaErrorをコールし、エラー・コードを確認する必要があります。

ttXlaUpdateDesc_tレコードがトランザクション・コミットの場合、基盤となるデータ・ストア・トランザクションまたはデータベース・トランザクションがコミットされます。 ttXlaApplyで他のトランザクション・コミットは実行されません。 パラメータtestがtrueの場合は、レコードの更新および削除のために、更新記述内の古い値がデータ・ストアの現在の内容と比較されます。 更新記述内の古い値がデータ・ストアの対応する行と一致しない場合、この関数は更新を拒否して、sb_ErrXlaTupleMismatchエラーを返します。

この関数の使用方法については、「レプリケーション・メカニズムとしてのXLAの使用」を参照してください。

注意: 表定義が最初にトランザクション・ログに書き込まれてから変更された場合、ttXlaApplyは使用できません。 文のレベルではなく、行のレベルで一意キー制約および外部キー制約がチェックされます。

必要な権限

システム権限ADMINが必要です。

ttXlaApply処理の対象となるターゲット・データベースでは、他の権限が必要になる場合があります。 たとえば、ターゲット・データベースにCREATETAB（表の作成）レコードを適用するには、必要に応じて、CREATE TABLEまたはCREATE ANY TABLE権限を持つ必要があります。

構文

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

パラメータ

パラメータ	型	説明
handle	ttXlaHandle_h	データ・ストアのトランザクション・ログ・ハンドル。
record	ttXlaUpdateDesc_t *	SQL文を生成するトランザクション。
test	SQLINTEGER	古い値のテスト（0 =テスト無効、1 =テスト有効）。

結果

コールが成功すると、SQL_SUCCESSが返されます。返されない場合は、ttXlaErrorを使用してエラーをレポートします。

testが1で、ttXlaApplyで更新の競合が検出されると、sb_ErrXlaTupleMismatchエラーが返されます。

例

この例では、既存のレコードの以前の値をテストせずに、更新をデータ・ストアに適用します。

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

注意

ttXlaApplyをコールすると、更新が同時トランザクションでタイムアウトまたはデッドロックする可能性があります。 この場合は、アプリケーションによって、トランザクションをロールバックし、更新を再適用してください。

参照

「ttXlaCommit」
「ttXlaRollback」
「ttXlaLookup」
「ttXlaTableCheck」
「ttXlaGenerateSQL」

---

ttXlaClose

説明

ttXlaPersistOpenによってオープンされたXLAhandleをクローズします。 この関数の使用方法については、「XLAアプリケーションの終了」を参照してください。

必要な権限

システム権限XLAが必要です。

構文

SQLRETURN ttXlaClose(ttXlaHandle_h handle)

パラメータ

パラメータ	型	説明
handle	ttXlaHandle_h	データ・ストアのODBCハンドル。

結果

コールが成功すると、SQL_SUCCESSが返されます。返されない場合は、ttXlaErrorを使用してエラーをレポートします。

前述の例でオープンしたXLAハンドルをクローズするには、次のコールを実行します。

rc = ttXlaClose(xlahandle);

参照

ttXlaPersistOpen

---

ttXlaCommit

説明

handleに対して適用中の現行のトランザクションをコミットします。 トランザクションが完了しているかどうかに関係なく、このルーチンはトランザクションをコミットします。 このルーチンをコールすると、ttXlaApplyによってレポートされた一時的なエラー（タイムアウトまたはデッドロック）に応答できます。ttXlaApplyは、エラーが発生しなければ現在のトランザクションを適用します。

この関数の使用方法については、「タイムアウトおよびデッドロックのエラーの処理」を参照してください。

必要な権限

システム権限XLAが必要です。

構文

SQLRETURN ttXlaCommit(ttXlaHandle_h handle)

パラメータ

パラメータ	型	説明
handle	ttXlaHandle_h	データ・ストアのトランザクション・ログ・ハンドル。

結果

コールが成功すると、SQL_SUCCESSが返されます。返されない場合は、ttXlaErrorを使用してエラーをレポートします。

例

rc = ttXlaCommit(xlahandle);

参照

「ttXlaApply」
「ttXlaRollback」
「ttXlaLookup」
「ttXlaTableCheck」
「ttXlaGenerateSQL」

---

ttXlaConfigBuffer

説明

この関数は、XLAが非永続モードの場合にのみ有効です。

ttXlaConfigBuffer関数を使用すると、XLAステージング・バッファのサイズを設定および取得できます。XLAは、XLAステージング・バッファでトランザクション・ログから取得した更新ログをステージングし、アプリケーションでの読取りを可能にします。

最初にステージング・バッファのサイズを設定するには、newSizeパラメータに値を指定し、oldSizeパラメータにNULL値を指定します。 ステージング・バッファの新しいサイズは、*newSizeから取得されます。 サイズが0（ゼロ）の場合は、ステージング・バッファの割当て禁止を意味します。

ステージング・バッファのサイズを変更するには、newSizeパラメータに値を指定し、oldSizeパラメータを指定します。 *oldSizeには、ステージング・バッファの以前のサイズが返されます。また、サイズが設定されていない場合は0（ゼロ）が返されます。

ステージング・バッファの現在のサイズを変更するのではなく取得するには、newSizeパラメータにNULL値を指定します。 ステージング・バッファの現在のサイズは*oldSizeに返されます。

ステージング・バッファのサイズを選択する場合は、バッファが小さすぎると、TimesTenの更新でバッファがいっぱいとなり、それ以上の更新が拒否されることを考慮してください。また、バッファに大量の領域を割り当てすぎると、メモリーが浪費されます。

ステージング・バッファのサイズは、設定後、随時サイズ変更できます。ただし、サイズ変更を行うと、現在のバッファがコピーされるため、大幅にパフォーマンスが低下する場合があります。

ステージング・バッファ・サイズの変更はすぐに実行されます。バッファのサイズが変更されると、ttXlaNextUpdateまたはttXlaNextUpdateWaitへの以前のコールによって返したレコードは無効になります。

1つのデータ・ストアに対して設定できるバッファは1つのみです。バッファのサイズが変更されると、ttXlaNextUpdateへの以前のコールによって返された値は無効になります。

注意: XLAステージング・バッファが0（ゼロ）以外のサイズに設定され、XLAリーダーが接続されていない場合、データ・ストアへの更新はバッファに書き込まれます。 ステージング・バッファがいっぱいになると、ユーザーがステージング・バッファを削除（サイズを0（ゼロ）に設定）するか、またはXLAリーダーを接続してバッファからの読取りを開始するまで、データベース処理を正常に完了することはできません。 より小さいサイズをステージング・バッファに指定し、その小さいサイズに現在の内容を格納できない場合、ステージング・バッファのサイズは変更されず、エラーが返されます。

必要な権限

システム権限XLAが必要です。

構文

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

パラメータ

パラメータ	型	説明
handle	ttXlaHandle_h	データ・ストアのトランザクション・ログ・ハンドル。
oldSize	out SQLUBIGINT *	ステージング・バッファの現在のサイズ。
newSize	SQLUBIGINT *	ステージング・バッファの新しいサイズ。

結果

コールが成功すると、SQL_SUCCESSが返されます。返されない場合は、ttXlaErrorを使用してエラーをレポートします。

例

この例では、次の宣言を想定しています。

SQLUBIGINT currentSize, requestedSize;

ステージング・バッファのサイズを変更せずにその現在のサイズを確認するには、次のように入力します。

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

ステージング・バッファのサイズを400,000バイトに設定するには、次のように入力します。

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

ステージング・バッファのサイズを400,000バイトに変更し、以前のサイズを取得するには、次のように入力します。

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

ステージング・バッファを削除するには、次のように入力します。

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

注意

バッファのサイズを変更すると現在のバッファがコピーされるため、パフォーマンスが大幅に低下する場合があります。より小さいサイズをステージング・バッファに指定し、その小さいサイズに現在の内容を格納できない場合、ステージング・バッファのサイズは変更されず、エラーが返されます。

参照

「ttXlaOpenTimesTen」
「ttXlaStatus」
「ttXlaResetStatus」

---

ttXlaConvertCharType

説明

colinfoおよびtupで示されている列データを、handleに関連付けられている接続キャラクタ・セットに変換し、結果をbufに格納します。

必要な権限

システム権限XLAが必要です。

構文

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

パラメータ

パラメータ	型	説明
handle	ttXlaHandle_h	データ・ストアのトランザクション・ログ・ハンドル。
colinfo	ttXlaColDesc_t *	列記述を保持するバッファへのポインタ。
tup	void *	変換されるデータ。
buf	void *	変換されたデータが格納される場所。
buflen	size_t	変換されたデータが格納されるバッファのサイズ。

結果

コールが成功すると、SQL_SUCCESSが返されます。返されない場合は、ttXlaErrorを使用してエラーをレポートします。

---

ttXlaDateToODBCCType

説明

TTXLA_DATE_TT値を、アプリケーションで使用可能なODBC C値に変換します。この関数の使用方法については、「複合データ型の変換」を参照してください。

この関数は、TTXLA_DATE_TTデータ型の列に対してのみコールします。データ型は、ttXlaGetColumnInfo関数によって返されるttXlaColDesc_t構造体から取得できます。

必要な権限

システム権限XLAが必要です。

構文

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

パラメータ

パラメータ	型	説明
fromData	void *	トランザクション・ログから返されたDATE値へのポインタ。
returnData	out DATE_STRUCT *	変換された日付を保持するように割り当てられた記憶域へのポインタ。

結果

コールが成功すると、SQL_SUCCESSが返されます。返されない場合は、ttXlaErrorを使用してエラーをレポートします。

---

ttXlaDecimalToCString

説明

TTXLA_DECIMAL_TT値を、アプリケーションで使用可能な文字列に変換します。 scaleおよびprecisionの値は、ttXlaGetColumnInfo関数によって返されるttXlaColDesc_t構造体から取得できます。 scaleパラメータは、小数点以下の最大桁数を指定します。DECIMAL値が1より大きい場合、precisionパラメータは小数点をはさんだ最大桁数を指定します。DECIMAL値が1より小さい場合、precisionはscaleと同じになります。

この関数は、TTXLA_DECIMAL_TT型の列に対してのみコールします。データ型は、ttXlaGetColumnInfo関数によって返されるttXlaColDesc_t構造体から取得できます。

この関数の使用方法については、「複合データ型の変換」を参照してください。

必要な権限

システム権限XLAが必要です。

構文

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

パラメータ

パラメータ	型	説明
fromData	void *	トランザクション・ログから返されたDECIMAL値へのポインタ。
returnData	out char *	変換された文字列を保持するように割り当てられた記憶域へのポインタ。
precision	SQLSMALLINT	fromDataが1より大きい場合、precisionは小数点をはさんだ最大桁数になります。 fromDataが1より小さい場合、precisionはscaleと同じになります。
scale	SQLSMALLINT	小数点以下の最大桁数。

結果

コールが成功すると、SQL_SUCCESSが返されます。返されない場合は、ttXlaErrorを使用してエラーをレポートします。

例

この例では、ttXlaColDesc_t構造体からoffset、precisionおよびscaleの値を取得し、トランザクション・ログ・レコードに返された行からDECIMAL値pColValを取得するためにoffsetを使用していると想定しています。

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

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

---

ttXlaDeleteBookmark

説明

指定したhandleに関連付けられているブックマークを削除します。ブックマークは、削除するとアクセスできなくなります。ブックマークの識別子は、別のブックマークに再利用できます。ブックマークを削除すると、データ・ストア・ハンドルとの関連が失われ、XLANONEオプションを指定して永続接続をオープンした場合と同じ結果になります。

ブックマークを使用している場合は、不要になるまで削除できません。

この関数の使用方法については、「ブックマークの削除」を参照してください。

注意: この関数をTimesTenの組込みプロシージャttXlaBookmarkDeleteと混同しないでください（『Oracle TimesTen In-Memory Databaseリファレンス』のttXlaBookmarkDeleteに関する項を参照）。 レプリケーション・エージェントの実行中は、レプリケートされたブックマークを削除できません。

必要な権限

システム権限XLAが必要です。

構文

SQLRETURN ttXlaDeleteBookmark(ttXlaHandle_h handle)

パラメータ

パラメータ	型	説明
handle	ttXlaHandle_h	トランザクション・ログ・ハンドル。

結果

コールが成功すると、SQL_SUCCESSが返されます。返されない場合は、ttXlaErrorを使用してエラーをレポートします。

例

xlahandleのブックマークを削除します。

rc = ttXlaDeleteBookmark(xlahandle);

参照

「ttXlaPersistOpen」
「ttXlaGetLSN」
「ttXlaSetLSN」

---

ttXlaError

説明

特定のhandleに対して以前コールした際に発生したエラーの詳細をレポートします。 ttXlaErrorへの後続のコールで、複数のエラーが返される場合があります。エラー・スタックは、ttXlaError自体およびttXlaErrorRestart以外の関数をコールするたびに消去されます。

この関数の使用方法については、「XLAエラーの処理」を参照してください。

必要な権限

システム権限XLAが必要です。

構文

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

パラメータ

パラメータ	型	説明
handle	ttXlaHandle_h	データ・ストアのトランザクション・ログ・ハンドル。
errCode	out SQLINTEGER *	errMessageバッファにコピーされるエラー・メッセージのコード。
errMessage	out char *	エラー・テキストが保持されるバッファ。
maxLen	SQLINTEGER	errMessageバッファの最大長。
retLen	out SQLINTEGER *	エラー・メッセージの実際のサイズ。

結果

エラー情報が返される場合はSQL_SUCCESSを返し、エラー・スタックにそれ以上エラーがない場合はSQL_NO_DATA_FOUNDを返します。 errMessageバッファの大きさが十分でない場合、ttXlaErrorはSQL_SUCCESS_WITH_INFOを返します。

例

エラー・スタックに複数のエラーが存在する可能性があります。 この例では、それらをすべて読み取る方法を示します。

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

注意

複数のスレッドを使用して単一のXLA接続のTimesTenトランザクション・ログにアクセスすると、同時アクセスを制御するためのラッチが作成されます。なんらかの理由でスレッドでラッチを取得できない場合、XLA関数はSQL_INVALID_HANDLEを返します。

参照

「ttXlaErrorRestart」

---

ttXlaErrorRestart

説明

アプリケーションでエラーを再度読み取ることができるように、エラー・スタックをリセットします。この関数の使用方法については、「XLAエラーの処理」を参照してください。

必要な権限

システム権限XLAが必要です。

構文

SQLRETURN ttXlaErrorRestart(ttXlaHandle_h handle)

パラメータ

パラメータ	型	説明
handle	ttXlaHandle_h	データ・ストアのトランザクション・ログ・ハンドル。

結果

コールが成功すると、SQL_SUCCESSが返されます。返されない場合は、ttXlaErrorを使用してエラーをレポートします。

例

rc = ttXlaErrorRestart(xlahandle);

参照

「ttXlaError」

---

ttXlaGenerateSQL

説明

更新recordの結果を示すSQL DMLまたはDDL文を生成します。生成された文は、データ・ストアにもデータベースにも適用されません。 かわりに、文は、最大サイズがmaxLenパラメータによって指定される特定のbufferに返されます。バッファの実際のサイズはactualLenによって返されます。更新および削除のレコードの場合、正しいSQLを生成するために、ttXlaGenerateSQLには、NULL値可能でない列に対する主キー索引または一意索引が必要です。

生成されたSQL文は、XLAハンドルのODBC接続に関係付けられている接続キャラクタ・セットでエンコードされます。

「TimesTen以外のデータ・ストアへの更新のレプリケート」も参照してください。

必要な権限

システム権限XLAが必要です。

構文

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

パラメータ

パラメータ	型	説明
handle	ttXlaHandle_h	データ・ストアのトランザクション・ログ・ハンドル。
record	ttXlaUpdateDesc_t *	SQLに変換されるレコード。
buffer	out char *	変換されたSQL文の場所。
maxLen	SQLINTEGER	バッファの最大長（バイト）。
actualLen	out SQLINTEGER *	バッファの実際の長さ（バイト）。

結果

コールが成功すると、SQL_SUCCESSが返されます。返されない場合は、ttXlaErrorを使用してエラーをレポートします。

例

この例では、更新レコードによって表現されるUPDATEに相当するSQL文のテキストを生成します。

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

SQLINTEGER actualLength;

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

注意

ttXlaGenerateSQL関数は、削除された表、またはレコードが生成された後で変更された表に関連付けられている更新レコードに対してはSQL文を生成できません。

参照

「ttXlaApply」
「ttXlaCommit」
「ttXlaRollback」
「ttXlaLookup」
「ttXlaTableCheck」

---

ttXlaGetColumnInfo

説明

表内のすべての列に関する情報を取得します。通常、*nreturnedは、colinfoに返される列の数に設定されます。 systemTableIDまたはuserTableIDパラメータは、目的の表について記述します。 このコールは、表の定義内の変更に対してシリアライズされます。

この関数の使用方法については、「列記述の取得」を参照してください。

必要な権限

システム権限XLAが必要です。

構文

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

パラメータ

パラメータ	型	説明
handle	ttXlaHandle_h	データ・ストアのトランザクション・ログ・ハンドル。
systemTableID	SQLUBIGINT	表のシステムID。
userTableID	SQLUBIGINT	表のユーザーID。
colinfo	out ttXlaColDesc_t *	maxcols列の個別の記述を保持できる十分な大きさのバッファへのポインタ。
maxcols	SQLINTEGER	colInfoバッファに格納可能な列の最大数。この表にmaxcolsを超える列を含めると、エラーが返されます。
nreturned	out SQLINTEGER *	列の数が返されます。

結果

コールが成功すると、SQL_SUCCESSが返されます。返されない場合は、ttXlaErrorを使用してエラーをレポートします。

例

この例では、次の定義を想定しています。

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

システム表識別子を使用して最大20列の記述を取得するには、次のコールを実行します。

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

ユーザー表識別子も、同様に使用できます。

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

返された行内の列データにアクセスする方法の詳細および例については、「ttXlaColDesc_t」を参照してください。

参照

「ttXlaGetTableInfo」
「ttXlaDecimalToCString」
「ttXlaDateToODBCCType」
「ttXlaTimeToODBCCType」
「ttXlaTimeStampToODBCCType」

---

ttXlaGetLSN

説明

handleで指定された接続の現行読取りログ・レコード識別子を返します。 この関数の使用方法については、「ブックマークの動作」を参照してください。

必要な権限

システム権限XLAが必要です。

構文

SQLRETURN ttXlaGetLSN(ttXlaHandle_h handle,
                      out tt_XlaLsn_t *LSN)

パラメータ

パラメータ	型	説明
handle	ttXlaHandle_h	データ・ストアのトランザクション・ログ・ハンドル。
LSN	out tt_XlaLsn_t *	ハンドルの現行読取りログ・レコード識別子。

注意: tt_XlaLsn_tの、特にlogFileフィールドおよびlogOffsetフィールドの使用方法が以前のリリースとは異なる点に注意してください。これらのフィールドは、連続的に増加するLSNではなく、ログ・レコード識別子を参照します。「tt_XlaLsn_t」の注意を参照してください。

結果

コールが成功すると、SQL_SUCCESSが返されます。返されない場合は、ttXlaErrorを使用してエラーをレポートします。

例

この例では、現行読取りログ・レコード識別子CurLSNを返します。

tt_XlaLsn_t CurLSN;

rc = ttXlaGetLSN(xlahandle, &CurLSN);

参照

「ttXlaSetLSN」

---

ttXlaGetTableInfo

説明

表内の行に関する情報を取得します（ttXlaTblDesc_tデータ型に関する項を参照）。 userTableIDが0（ゼロ）以外の場合は、userTableIDの値を使用して目的の表を検出します。そうでない場合は、systemTableIDの値を使用して表を検出します。両方が0（ゼロ）の場合は、エラーが返されます。記述は、出力パラメータtblinfoに格納されます。 このコールは、表の定義内の変更に対してシリアライズされます。

必要な権限

システム権限XLAが必要です。

構文

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

パラメータ

パラメータ	型	説明
handle	ttXlaHandle_h	データ・ストアのトランザクション・ログ・ハンドル。
systemTableID	SQLUBIGINT	システム表ID。
userTableID	SQLUBIGINT	ユーザー表ID。
tblinfo	out ttXlaTblDesc_t *	行の情報。

結果

コールが成功すると、SQL_SUCCESSが返されます。返されない場合は、ttXlaErrorを使用してエラーをレポートします。

例

この例では、次の定義を想定しています。

ttXlaTblDesc_t tabinfo;
SQLUBIGINT systemTableID, userTableID;

システム識別子を使用して表の情報を取得するには、ttXlaTableByNameまたは他の方法を使用してシステム表識別子を検出して次のコールを実行します。

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

また、表の情報は、ユーザー表識別子を使用して取得することもできます。

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

参照

「ttXlaGetColumnInfo」

---

ttXlaGetVersion

説明

この関数は、古いバージョンのXLA用に作成されたXLAアプリケーションを新しいバージョンで動作させるために、ttXlaSetVersionと組み合せて使用します。 通常、configured versionが古いバージョンで、actual versionが新しいバージョンです。

ttXlaGetVersionは、現在構成されているXLAのバージョンを取得して、configuredVersionパラメータに格納します。基礎となるXLAの実際のバージョンはactualVersionに格納されます。 ttXlaSetVersionをコールしたため、コールごとにconfiguredVersionの結果が異なる場合がありますが、actualVersionの結果は同じままです。

この関数の使用方法については、「XLA永続モード」を参照してください。

必要な権限

システム権限XLAが必要です。

構文

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

パラメータ

パラメータ	型	説明
handle	ttXlaHandle_h	データ・ストアのトランザクション・ログ・ハンドル。
configuredVersion	out ttXlaVersion_t *	構成されているXLAのバージョン。
actualVersion	out ttXlaVersion_t *	XLAの実際のバージョン。

結果

コールが成功すると、SQL_SUCCESSが返されます。返されない場合は、ttXlaErrorを使用してエラーをレポートします。

例

この例では、次の指示を想定しています。

ttXlaVersion_t configured, actual;

現行のバージョン構成を確認するには、次のコールを実行します。

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

参照

「ttXlaVersionCompare」
「ttXlaSetVersion」

---

ttXlaLookup

説明

この関数は、keysパラメータに指定されているキー値を持つ特定の表のレコードを検索します。 keysおよびresultレコードの書式は、通常の行の書式と同じです。この関数では、基礎となる表に主キーが必要です。

必要な権限

システム権限XLAが必要です。

構文

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

パラメータ

パラメータ	型	説明
handle	ttXlaHandle_h	データ・ストアのトランザクション・ログ・ハンドル。
table	ttXlaTblDesc_t *	検索する表。
keys	void *	表に対して定義された構造内のレコード。表の主キーの一部であるキー・レコードの列のみが調べられます。
result	out void *	検出されたレコードは、resultにコピーされます。一致するキー列を持つレコードが存在しない場合は、エラーが返されます。
maxsize	SQLINTEGER	resultバッファに格納可能な最大レコードのサイズ。
retsize	out SQLINTEGER *	レコードの実際のサイズ。

結果

コールが成功すると、SQL_SUCCESSが返されます。返されない場合は、ttXlaErrorを使用してエラーをレポートします。

例

この例では、一組の整数キー値を指定してレコードを調べます。 このコールの前に、目的の表がtableに記述され、キー列が設定されているレコードがkeybufferに含まれている必要があります。

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

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

参照

「ttXlaApply」
「ttXlaCommit」
「ttXlaRollback」
「ttXlaTableCheck」
「ttXlaGenerateSQL」

---

ttXlaNextUpdate

説明

この関数は、トランザクション・ログから最大maxrecordsの更新レコードをフェッチし、コミットされたトランザクションに関連付けられているレコードをrecordsバッファに返します。実際に返されたレコードの数が出力パラメータnreturnedに記録されます。 この関数を使用するには、ブックマークがデータ・ストア内に存在し、関数で使用する接続と関連付けられる必要があります。

トランザクション・ログを永続モードで処理する場合は、ttXlaNextUpdateをコールするたびに、最後に読み取られたレコードにブックマークが再設定され、次のレコードのリストを返すためにttXlaNextUpdateへの次のコールが有効にされます。

この関数の使用方法については、「トランザクション・ログからの更新レコードの取得」を参照してください。

必要な権限

システム権限XLAが必要です。

構文

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

パラメータ

パラメータ	型	説明
handle	ttXlaHandle_h	データ・ストアのトランザクション・ログ・ハンドル。
record	out ttXlaUpdateDesc_t ***	完了したトランザクション・レコードを保持するバッファ。
maxrecords	SQLINTEGER	フェッチされるレコードの最大数。
nreturned	out SQLINTEGER *	実際に返されたレコードの数。使用可能な更新データがない場合は、0（ゼロ）が返されます。

結果

コールが成功すると、SQL_SUCCESSが返されます。返されない場合は、ttXlaErrorを使用してエラーをレポートします。

例

この例では、最大100個のレコードを取得し、各レコードが処理されるループについて記述します。

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

注意

追跡ステータスに関係なく、すべてのデータ定義文に対して更新が生成されます。また、更新はブックマークに関係付けられているすべての追跡対象表でのデータ更新処理に対して生成されます。

また、表および列に対するアプリケーション・レベルの識別子の割当て、表の追跡ステータスの変更などの特定の処理でも更新が生成されます。

参照

「ttXlaNextUpdateWait」
「ttXlaAcknowledge」

---

ttXlaNextUpdateWait

説明

ttXlaNextUpdate関数と同様の処理を行いますが、使用可能なレコードがトランザクション・ログにない場合に待機する秒数を指定するパラメータsecondsがあります。実際に待機する秒数は、secondsに指定された値より最大で2秒長くなる場合があります。

「トランザクション・ログからの更新レコードの取得」も参照してください。

必要な権限

システム権限XLAが必要です。

構文

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

パラメータ

パラメータ	型	説明
handle	ttXlaHandle_h	データ・ストアのトランザクション・ログ・ハンドル。
record	out ttXlaUpdateDesc_t ***	完了したトランザクション・レコードを保持するバッファ。
maxrecords	SQLINTEGER	フェッチされるレコードの最大数。 注意: 有効な最大値は1000レコードです。
nreturned	out SQLINTEGER *	実際に返されたレコードの数。 secondsの待機時間内に使用可能な更新データがない場合は、0（ゼロ）が返されます。
seconds	SQLINTEGER	ログが空の場合に待機する時間（秒）。

結果

コールが成功すると、SQL_SUCCESSが返されます。返されない場合は、ttXlaErrorを使用してエラーをレポートします。

例

最大100個のレコードを取得し、使用可能なレコードがトランザクション・ログにない場合に最大60秒待機します。

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

参照

「ttXlaNextUpdate」
「ttXlaAcknowledge」

---

ttXlaNumberToBigInt

説明

TTXLA_NUMBER値を、アプリケーションで使用可能なSQLBIGINT値に変換します。

この関数は、TTXLA_NUMBER型の列に対してのみコールします。データ型は、ttXlaGetColumnInfo関数によって返されるttXlaColDesc_t構造体から取得できます。

必要な権限

システム権限XLAが必要です。

構文

SQLRETURN ttXlaNumberToBigInt(void *fromData,
                              SQLBIGINT *bint)

パラメータ

パラメータ	型	説明
fromData	void *	トランザクション・ログから返されたNUMBER値へのポインタ。
bint	SQLBIGINT *	XLA NUMBER値から変換されたSQLBIGINT値。

結果

成功すると、SQL_SUCCESSが返されます。返されない場合は、ttXlaErrorを使用してエラーをレポートします。

---

ttXlaNumberToCString

説明

TTXLA_NUMBER値を、アプリケーションで使用可能なキャラクタ文字列に変換します。

この関数は、TTXLA_NUMBER型の列に対してのみコールします。データ型は、ttXlaGetColumnInfo関数によって返されるttXlaColDesc_t構造体から取得できます。

必要な権限

システム権限XLAが必要です。

構文

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

パラメータ

パラメータ	型	説明
fromData	void *	トランザクション・ログから返されたNUMBER値へのポインタ。
buf	char *	変換されたデータが格納される場所。
buflen	int	変換されたデータが格納されるバッファのサイズ。
reslen	int *	buflen >= reslenの場合、reslenは書き込まれたバイト数になります。 buflen <reslenの場合、reslenはバッファが十分大きかったら書き込まれたはずのバイト数になります。

結果

コールが成功すると、SQL_SUCCESSが返されます。返されない場合は、ttXlaErrorを使用してエラーをレポートします。

---

ttXlaNumberToDouble

説明

TTXLA_NUMBER値を、アプリケーションで使用可能な長い浮動小数点数値に変換します。

この関数は、TTXLA_NUMBER型の列に対してのみコールします。データ型は、ttXlaGetColumnInfo関数によって返されるttXlaColDesc_t構造体から取得できます。

必要な権限

システム権限XLAが必要です。

構文

SQLRETURN ttXlaNumberToDouble(void *fromData,
                              double *dbl)

パラメータ

パラメータ	型	説明
fromData	void *	トランザクション・ログから返されたNUMBER値へのポインタ。
dbl	double *	XLA NUMBER値から変換された長い浮動小数点数値。

結果

コールが成功すると、SQL_SUCCESSが返されます。返されない場合は、ttXlaErrorを使用してエラーをレポートします。

---

ttXlaNumberToInt

説明

TTXLA_NUMBER値を、アプリケーションで使用可能なSQLINTEGER値に変換します。

この関数は、TTXLA_NUMBER型の列に対してのみコールします。データ型は、ttXlaGetColumnInfo関数によって返されるttXlaColDesc_t構造体から取得できます。

必要な権限

システム権限XLAが必要です。

構文

SQLRETURN ttXlaNumberToInt(void *fromData,
                           SQLINTEGER *ival)

パラメータ

パラメータ	型	説明
fromData	void *	トランザクション・ログから返されたNUMBER値へのポインタ。
ival	SQLINTEGER *	XLA NUMBER値から変換されたSQLINTEGER値。

結果

コールが成功すると、SQL_SUCCESSが返されます。返されない場合は、ttXlaErrorを使用してエラーをレポートします。

---

ttXlaNumberToSmallInt

説明

TTXLA_NUMBER値を、アプリケーションで使用可能なSQLSMALLINT値に変換します。

この関数は、TTXLA_NUMBER型の列に対してのみコールします。データ型は、ttXlaGetColumnInfo関数によって返されるttXlaColDesc_t構造体から取得できます。

必要な権限

システム権限XLAが必要です。

構文

SQLRETURN ttXlaNumberToSmallInt(void *fromData,
                                SQLSMALLINT *smint)

パラメータ

パラメータ	型	説明
fromData	void *	トランザクション・ログから返されたNUMBER値へのポインタ。
smint	SQLSMALLINT *	XLA NUMBER値から変換されたSQLSMALLINT値。

結果

コールが成功すると、SQL_SUCCESSが返されます。返されない場合は、ttXlaErrorを使用してエラーをレポートします。

---

ttXlaNumberToTinyInt

説明

TTXLA_NUMBER値を、アプリケーションで使用可能な小さい整数値に変換します。

この関数は、TTXLA_NUMBER型の列に対してのみコールします。データ型は、ttXlaGetColumnInfo関数によって返されるttXlaColDesc_t構造体から取得できます。

必要な権限

システム権限XLAが必要です。

構文

SQLRETURN ttXlaNumberToTinyInt(void *fromData,
                               SQLCHAR *tiny)

パラメータ

パラメータ	型	説明
fromData	void *	トランザクション・ログから返されたNUMBER値へのポインタ。
tiny	SQLCHAR *	XLA NUMBER値から変換された小さい整数値。

結果

コールが成功すると、SQL_SUCCESSが返されます。返されない場合は、ttXlaErrorを使用してエラーをレポートします。

---

ttXlaNumberToUInt

説明

TTXLA_NUMBER値を、アプリケーションで使用可能な符号なし整数値に変換します。

この関数は、TTXLA_NUMBER型の列に対してのみコールします。データ型は、ttXlaGetColumnInfo関数によって返されるttXlaColDesc_t構造体から取得できます。

必要な権限

システム権限XLAが必要です。

構文

SQLRETURN ttXlaNumberToInt(void *fromData,
                           SQLUINTEGER *ival)

パラメータ

パラメータ	型	説明
fromData	void *	トランザクション・ログから返されたNUMBER値へのポインタ。
ival	SQLUINTEGER *	XLA NUMBER値から変換された整数値。

結果

コールが成功すると、SQL_SUCCESSが返されます。返されない場合は、ttXlaErrorを使用してエラーをレポートします。

---

ttXlaOpenTimesTen

説明

TimesTenデータ・ストアに対するトランザクション・ログ・ハンドルを初期化し、非永続モードでのトランザクション・ログへのアクセスを有効にします。 hdbcパラメータは、TimesTenデータ・ストアに対するODBC接続ハンドルで、更新の適用に使用します。 ttXlaCloseでクローズするまで、この接続に対して他のODBCコールは発行しないでください。 handleパラメータは、このコールによって初期化し、更新を適用する後続の各コールで指定する必要があります。

非永続モードでは、いずれの時点でも1つのアプリケーションでのみトランザクション・ログから読取りを実行できます。 詳細は、「非永続モードでのXLAの初期化」を参照してください。

注意: ほとんどのアプリケーションで、ttXlaPersistOpenを使用して、XLAを永続モードで初期化する必要があります。

必要な権限

システム権限XLAが必要です。

構文

SQLRETURN ttXlaOpenTimesTen(SQLHDBC hdbc,
                            out ttXlaHandle_h *handle)

パラメータ

パラメータ	型	説明
hdbc	SQLHDBC	データ・ストアのODBCハンドル。
handle	out ttXlaHandle_h *	データ・ストアのトランザクション・ログ・ハンドル。

結果

コールが成功すると、SQL_SUCCESSが返されます。返されない場合は、ttXlaErrorを使用してエラーをレポートします。

次の例では、トランザクション・ログを非永続モードでオープンし、ODBC接続のxlahandleという名前のハンドルを返します。

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

注意

TimesTenでは、同じXLAハンドルに対して複数のスレッドは使用しないことをお薦めします。マルチスレッド・アプリケーションでは、ttXlaPersistOpenを使用してスレッドごとに別々のXLAハンドルを作成する必要があります。複数のスレッドで同じXLAハンドルを使用する必要がある場合は、1つのスレッドのみが一度に1つのXLA処理を実行できるように、mutexを使用してそのXLAハンドルへのスレッド・アクセスをシリアライズします。

参照

「ttXlaConfigBuffer」
「ttXlaStatus」
「ttXlaResetStatus」
「ttXlaClose」

---

ttXlaOraDateToODBCTimeStamp

説明

TTXLA_DATE値をODBCタイムスタンプに変換します。

この関数は、TTXLA_DATE型の列に対してのみコールします。データ型は、ttXlaGetColumnInfo関数によって返されるttXlaColDesc_t構造体から取得できます。

必要な権限

システム権限XLAが必要です。

構文

SQLRETURN ttXlaOraDateToODBCTimeStamp(void *fromData,
                                      TIMESTAMP_STRUCT *returnData)

パラメータ

パラメータ	型	説明
fromData	void *	トランザクション・ログから返されたNUMBER値へのポインタ。
returnData	TIMESTAMP_STRUCT *	XLA Oracle DATE値から変換されたODBCタイムスタンプ値。

結果

コールが成功すると、SQL_SUCCESSが返されます。返されない場合は、ttXlaErrorを使用してエラーをレポートします。

---

ttXlaOraTimeStampToODBCTimeStamp

説明

TTXLA_TIMESTAMP値をODBCタイムスタンプに変換します。

この関数は、TTXLA_TIMESTAMP型の列に対してのみコールします。データ型は、ttXlaGetColumnInfo関数によって返されるttXlaColDesc_t構造体から取得できます。

構文

SQLRETURN ttXlaOraTimeStampToODBCTimeStamp(void *fromData,
                                           TIMESTAMP_STRUCT *returnData)

必要な権限

システム権限XLAが必要です。

パラメータ

パラメータ	型	説明
fromData	void *	トランザクション・ログから返されたNUMBER値へのポインタ。
returnData	TIMESTAMP_STRUCT *	XLA Oracle TIMESTAMP値から変換されたODBCタイムスタンプ値。

結果

コールが成功すると、SQL_SUCCESSが返されます。返されない場合は、ttXlaErrorを使用してエラーをレポートします。

---

ttXlaPersistOpen

説明

TimesTenデータ・ストアに対するトランザクション・ログ・ハンドルを初期化して、永続モードでのトランザクション・ログへのアクセスを有効にします。 hdbcパラメータは、TimesTenデータ・ストアへのODBC接続ハンドルです。ODBC接続ごとに1つのXLAハンドルのみを作成します。ODBC接続に対してXLAハンドルを作成してから、ttXlaCloseでクローズするまで、ODBC接続に対して他のODBCコールは発行しないでください。

tagは、永続ブックマークを識別する文字列です（「XLAブックマークについて」を参照）。 tagでは、optionsパラメータの指定に応じて、新しいブックマーク（レプリケートされていないブックマークまたはレプリケートされたブックマーク）、またはシステムにすでに存在するブックマークを識別できます。 handleパラメータは、このコールによって初期化され、XLAに対する後続の各コールで指定する必要があります。

一部の処理は、ブックマークなしで実行できます。 これらのタイプの処理を実行する場合は、XLANONEオプションを使用して、ブックマークなしでトランザクション・ログにアクセスできます。 次に、ブックマークなしでは実行できない処理を示します。

• ttXlaAcknowledge

• ttXlaGetLSN

• ttXlaSetLSN

• ttXlaNextUpdate

• ttXlaNextUpdateWait

永続モードでは、複数のアプリケーションが同時にトランザクション・ログから読取りを実行できます。 この関数の使用方法については、「XLAの初期化およびXLAハンドルの取得」を参照してください。

この関数が成功すると、XLAは自動コミット・モードをOFFに設定します。

この関数が失敗しても、まだハンドルを作成する場合は、メモリー・リークを防ぐためにハンドルを閉じる必要があります。

必要な権限

システム権限XLAが必要です。

構文

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

パラメータ

パラメータ	型	説明
hdbc	SQLHDBC	データ・ストアのODBCハンドル。
tag	SQLCHAR *	永続ブックマークの識別子。 optionsがXLANONEに設定されている場合はNULLを指定できます。 許容最大長は31です。
options	SQLUINTEGER	ブックマーク・オプションは、次のとおりです。 XLANONE: ブックマークなしで接続します。 tagフィールドは無視されます。 XLACREAT: 新しいレプリケートされていないブックマークを作成します。ブックマークがすでに存在する場合は失敗します。 XLAREPL: 新しいレプリケートされたブックマークを作成します。ブックマークがすでに存在する場合は失敗します。 XLAREUSE: 既存のブックマーク（レプリケートされていないブックマークまたはレプリケートされたブックマーク）に関連付けます。ブックマークが存在しない場合は失敗します。
handle	out ttXlaHandle_h *	このコールによって返されるトランザクション・ログ・ハンドル。このコールによって領域が割り当てられます。領域を解放するには、ttXlaCloseをコールする必要があります。

結果

コールが成功すると、SQL_SUCCESSが返されます。返されない場合は、ttXlaErrorを使用してエラーをレポートします。

例

この例では、トランザクション・ログを永続モードでオープンし、xlahandleというハンドルを返して、mybookmarkという新しいレプリケートされていないブックマークを作成します。

SQLHDBC hdbc;
ttXlaHandle_h xlahandle;

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

または、次のように新しいレプリケートされたブックマークを作成します。

SQLHDBC hdbc;
ttXlaHandle_h xlahandle;

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

注意

マルチスレッド・アプリケーションでは、スレッドごとに別々のXLAハンドルを作成する必要があります。複数のスレッドで同じXLAハンドルを使用する必要がある場合は、1つのスレッドのみが一度に1つのXLA処理を実行できるように、mutexを使用してそのXLAハンドルへのスレッド・アクセスをシリアライズします。

参照

「ttXlaClose」
「ttXlaDeleteBookmark」
「ttXlaGetLSN」
「ttXlaSetLSN」

---

ttXlaResetStatus

説明

この関数は、XLAが非永続モードの場合にのみ有効です。

ttXlaStatusによって返されるttXlaStatus_t構造体にレポートされるすべてのXLAのステータス・カウンタをリセットします。現在、xlabufminfreeの値のみがリセットされます。

必要な権限

システム権限XLAが必要です。

構文

SQLRETURN ttXlaResetStatus(ttXlaHandle_h handle)

パラメータ

パラメータ	型	説明
handle	ttXlaHandle_h	データ・ストアのトランザクション・ログ・ハンドル。

結果

コールが成功すると、SQL_SUCCESSが返されます。返されない場合は、ttXlaErrorを使用してエラーをレポートします。

例

次の例では、XLAのステータス・カウンタをリセットします。

rc = ttXlaResetStatus(xlahandle);

参照

「ttXlaOpenTimesTen」
「ttXlaConfigBuffer」
「ttXlaStatus」

---

ttXlaRollback

説明

handleに対して適用中の現行のトランザクションをロールバックします。このルーチンをコールすると、ttXlaApplyによってレポートされた一時的なエラー（タイムアウトまたはデッドロック）に応答できます。

この関数の使用方法については、「タイムアウトおよびデッドロックのエラーの処理」を参照してください。

必要な権限

システム権限XLAが必要です。

構文

SQLRETURN ttXlaRollback(ttXlaHandle_h handle)

パラメータ

パラメータ	型	説明
handle	ttXlaHandle_h	データ・ストアのトランザクション・ログ・ハンドル。

結果

コールが成功すると、SQL_SUCCESSが返されます。返されない場合は、ttXlaErrorを使用してエラーをレポートします。

例

rc = ttXlaRollback(xlahandle);

参照

「ttXlaApply」
「ttXlaCommit」
「ttXlaLookup」
「ttXlaTableCheck」
「ttXlaGenerateSQL」

---

ttXlaRowidToCString

説明

ROWID値を、アプリケーションで使用可能な文字列値に変換します。

必要な権限

システム権限XLAが必要です。

構文

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

パラメータ

パラメータ	型	説明
fromData	void *	トランザクション・ログから返されたROWID値へのポインタ。
buf	char *	変換された文字列を保持するように割り当てられた記憶域へのポインタ。
buflen	int	変換された文字列の長さ。

結果

コールが成功すると、SQL_SUCCESSが返されます。返されない場合は、ttXlaErrorを使用してエラーをレポートします。

例

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

---

ttXlaSetLSN

説明

handleで指定されたデータ・ストアの現行読取りログ・レコード識別子を設定します。 指定するLSNの値が、ttXlaGetLSNから返されるはずです。 ユーザーが作成した値、現在のブックマークの初期読取りログ・レコード識別子より小さい値にはなりません。

この関数の使用方法については、「XLAブックマークについて」を参照してください。

必要な権限

システム権限XLAが必要です。

構文

SQLRETURN ttXlaSetLSN(ttXlaHandle_h handle,
                      tt_XlaLsn_t *LSN)

パラメータ

パラメータ	型	説明
handle	ttXlaHandle_h	データ・ストアのトランザクション・ログ・ハンドル。
LSN	tt_XlaLsn_t *	ハンドルの新しいログ・レコード識別子。

注意: tt_XlaLsn_tの、特にlogFileフィールドおよびlogOffsetフィールドの使用方法が以前のリリースとは異なる点に注意してください。これらのフィールドは、連続的に増加するLSNではなく、ログ・レコード識別子を参照します。「tt_XlaLsn_t」の注意を参照してください。

結果

コールが成功すると、SQL_SUCCESSが返されます。返されない場合は、ttXlaErrorを使用してエラーをレポートします。

例

この例では、現行読取りログ・レコード識別子をCurLSNに設定します。

tt_XlaLsn_t CurLSN;

rc = ttXlaSetLSN(xlahandle, &CurLSN);

参照

「ttXlaGetLSN」

---

ttXlaSetVersion

説明

アプリケーションで使用されるXLAのバージョンを設定します。このバージョンは、ttXlaGetVersionで返されるバージョンと同じか、または以前のバージョンである必要があります。

この関数の使用方法については、「XLA永続モード」を参照してください。

必要な権限

システム権限XLAが必要です。

構文

SQLRETURN ttXlaSetVersion(ttXlaHandle_h handle,
                          ttXlaVersion_t *version)

パラメータ

パラメータ	型	説明
handle	ttXlaHandle_h	データ・ストアのトランザクション・ログ・ハンドル。
version	ttXlaVersion_t *	必要なXLAのバージョン。

結果

コールが成功すると、SQL_SUCCESSが返されます。返されない場合は、ttXlaErrorを使用してエラーをレポートします。

例

構成されているバージョンをrequestedVersionで指定された値に設定するには、次のコールを実行します。

rc = ttXlaSetVersion(xlahandle, &requestedVersion);

参照

「ttXlaVersionCompare」
「ttXlaGetVersion」

---

ttXlaStatus

説明

この関数は、非永続モードでXLAを処理する場合にのみ有効です。

トランザクション・ログ・バッファおよびXLAステージング・バッファのステータス情報を取得し、ttXlaStatus_tデータ型の*statusパラメータに格納します。 このデータ構造体には、次のものが含まれます。

• ステージング・バッファ内の空き領域および使用されている領域。

• ステージング・バッファ内のトランザクションおよびレコードの数。

• トランザクション・ログ・バッファ内の空き領域および使用されている領域。

• システムで新しいトランザクション更新が受け入れられているかどうか

ttXlaStatus_t ->xlabufminfree値は、トランザクション・ログ・バッファ内の空き領域の最小数（バイト）で、ステージング・バッファの最適サイズを再計算する場合に有効な統計です。トランザクション・ログ・バッファを拡大および縮小すると、xlabufminfreeは最小領域を正確に反映しなくなります。 通常、ttXlaStatus_t ->xlabufminfreeフィールドの値を再設定するために使用されるttXlaResetStatusをコールして、xlabufminfreeをNULLに設定できます。 しばらく後で、ttXlaStatusをコールして新しい最小値を取得してから、最適なnewSize値を計算してttXlaConfigBuffer関数に渡します。

必要な権限

システム権限XLAが必要です。

構文

ttXlaStatus(ttXlaHandle_h handle, out ttXlaStatus_t *status)

パラメータ

パラメータ	型	説明
handle	ttXlaHandle_h	データ・ストアのトランザクション・ログ・ハンドル。
status	out ttXlaStatus_t *	現在のXLAのステータス。

結果

コールが成功すると、SQL_SUCCESSが返されます。返されない場合は、ttXlaErrorを使用してエラーをレポートします。

例

この例では、現在のXLAのステータスを取得します。

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

参照

「ttXlaOpenTimesTen」
「ttXlaConfigBuffer」
「ttXlaResetStatus」

---

ttXlaTableByName

説明

表またはビューの所有者および名前を指定して、表またはマテリアライズド・ビューのシステム表識別子およびユーザー表識別子を検出します。この関数の使用方法については、「更新を監視する表の指定」を参照してください。

必要な権限

システム権限XLAが必要です。

構文

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

パラメータ

パラメータ	型	説明
handle	ttXlaHandle_h	データ・ストアのトランザクション・ログ・ハンドル。
owner	char *	表またはビューの所有者の文字列。
name	char *	表またはビューの名前。
sysTableID	out SQLUBIGINT *	システム表IDが返されます。
userTableID	out SQLUBIGINT *	ユーザー表IDが返されます。

結果

コールが成功すると、SQL_SUCCESSが返されます。返されない場合は、ttXlaErrorを使用してエラーをレポートします。

例

表PURCHASING.INVOICESに関連付けられているシステム表IDおよびユーザー表IDを取得するには、次のコールを実行します。

SQLUBIGINT sysTableID;
SQLUBIGINT userTableID;

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

参照

「ttXlaTableStatus」

---

ttXlaTableCheck

説明

レプリケーション・メカニズムとしてXLAを使用する場合、この関数は、マスター・データ・ストアから受信したttXlaTblDesc_t構造体内の名前付き表が、handleに関連付けられているサブスクライバ・データ・ストアまたはデータベースと互換性があることを検証します。 compatパラメータは、表に互換性があるかどうかを示します。

この関数の使用方法については、「データ・ストア間での表の互換性の確認」を参照してください。

必要な権限

システム権限XLAが必要です。

構文

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

パラメータ

パラメータ	型	説明
handle	ttXlaHandle_h	データ・ストアのトランザクション・ログ・ハンドル。
table	ttXlaTblDesc_t *	表記述。
columns	ttXlaColDesc_t *	表の列記述。
compat	out SQLINTEGER *	互換性情報を返します。 1: 表に互換性がある。 0: 表に互換性がない。

結果

コールが成功すると、SQL_SUCCESSが返されます。返されない場合は、ttXlaErrorを使用してエラーをレポートします。

例

この例では、表の互換性を確認します。

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
     */
}

参照

「ttXlaApply」
「ttXlaCommit」
「ttXlaRollback」
「ttXlaLookup」
「ttXlaGenerateSQL」

---

ttXlaTableStatus

説明

表の更新ステータスを*oldstatusに返します。表は、ユーザーID（userTableID）またはシステムID（systemTableID）のいずれかで識別します。 userTableIDが0（ゼロ）以外の場合は、userTableIDの値を使用して表が検出されます。 そうでない場合は、systemTableIDが使用されます。両方が0（ゼロ）の場合は、エラーが返されます。

newstatusに値を指定すると、更新ステータスが*newstatusに設定されます。 ステータスが0（ゼロ）以外の場合は、systemTableIDで指定された表がXLAで使用可能であることを意味します。0（ゼロ）の場合は、表が追跡されないことを意味します。表の更新ステータスへの変更は、すぐに有効になります。

更新が実行された時点で表の更新追跡が有効になっていた場合にのみ、表への更新が追跡されます。このコールは、基礎となる表への更新に対してシリアライズされます。 このため、表を更新するトランザクションは、表のステータスが変更される完全前または完全後に実行されます。

ttXlaTableStatusを使用するには、ユーザーは永続モードでブックマークに接続する必要があります。 ttXlaTableStatusは、表に対する挿入、更新および削除を、表にサブスクライブしたブックマークにのみレポートします。ttXlaTableStatusは、DDLイベントをすべてのブックマークにレポートします。DDLイベントには、CREATAB、DROPTAB、CREAIND、DROPIND、CREATVIEW、DROPVIEW、CREATSEQ、DROPSEQ、ADDCOLS、DRPCOLS、TRUNCATE、SETTBLIおよびSETCOLIトランザクションが含まれています。

この関数の使用方法については、「更新を監視する表の指定」を参照してください。

必要な権限

システム権限XLAが必要です。

構文

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

パラメータ

パラメータ	型	説明
handle	ttXlaHandle_h	データ・ストアのトランザクション・ログ・ハンドル。
systemTableID	SQLUBIGINT	表のシステムID。
userTableID	SQLUBIGINT	表のユーザーID。
oldstatus	out SQLINTEGER *	XLAのステータス: 1 = Onまたは0 = Off。
newstatus	SQLINTEGER *	XLAのステータス: 1 = Onまたは0 = Off。

結果

コールが成功すると、SQL_SUCCESSが返されます。返されない場合は、ttXlaErrorを使用してエラーをレポートします。

例

次の例では、ttXlaTableByNameまたは他のなんらかの方法を使用して、システム表識別子またはユーザー表識別子が検出されていることを想定しています。

この例では、次の宣言を想定しています。

SQLUBIGINT systemTableID;
SQLUBIGINT userTableID;
SQLINTEGER currentStatus, requestedStatus;

システム表識別子を指定して表のステータスを検出するには、次のコールを実行します。

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

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

currentStatusの値は、表の更新追跡が有効になっている場合は0（ゼロ）以外になり、そうでない場合は0（ゼロ）になります。

システム表識別子を指定して表の更新追跡を有効にするには、次のように、リクエストするステータスを1に設定します。

requestedStatus = 1;

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

次の例に示すように、新しい更新追跡ステータスを設定し、1回のコールで現在のステータスを取得できます。

requestedStatus = 1;

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

前述のコールでは、システム表識別子による表の更新追跡が有効になり、以前の更新追跡ステータスが変数currentStatusに取得されます。

これらのすべての例は、ユーザー表識別子を使用しても実行できます。ユーザー表識別子によって表の更新追跡ステータスを取得するには、次のコールを実行します。

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

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

参照

「ttXlaTableByName」

---

ttXlaTimeToODBCCType

説明

TTXLA_TIME値を、アプリケーションで使用可能なODBC C値に変換します。この関数の使用方法については、「複合データ型の変換」を参照してください。

この関数は、TTXLA_TIME型の列に対してのみコールします。データ型は、ttXlaGetColumnInfo関数によって返されるttXlaColDesc_t構造体から取得できます。

必要な権限

システム権限XLAが必要です。

構文

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

パラメータ

パラメータ	型	説明
fromData	void *	トランザクション・ログから返されたTIME値へのポインタ。
returnData	out TIME_STRUCT *	変換された時間を保持するように割り当てられた記憶域へのポインタ。

結果

コールが成功すると、SQL_SUCCESSが返されます。返されない場合は、ttXlaErrorを使用してエラーをレポートします。

例

この例では、トランザクション・ログ・レコードに返された行からTIME値pColValを取得するために、ttXlaColDesc_t構造体に返されたoffset値を使用していると想定しています。

TIME_STRUCT time;

rc = ttXlaTimeToODBCCType(pColVal, &time);

---

ttXlaTimeStampToODBCCType

説明

TTXLA_TIMSTAMP_TT値を、アプリケーションで使用可能なODBC C値に変換します。この関数の使用方法については、「複合データ型の変換」を参照してください。

この関数は、TTXLA_TIMSTAMP_TT型の列に対してのみコールします。データ型は、ttXlaGetColumnInfo関数によって返されるttXlaColDesc_t構造体から取得できます。

必要な権限

システム権限XLAが必要です。

構文

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

パラメータ

パラメータ	型	説明
fromData	void *	トランザクション・ログから返されたTIMESTAMP値へのポインタ。
returnData	out TIMESTAMP_ STRUCT *	変換されたタイムスタンプを保持するように割り当てられた記憶域へのポインタ。

結果

成功すると、SQL_SUCCESSが返されます。返されない場合は、ttXlaErrorを使用してエラーをレポートします。

例

この例では、トランザクション・ログ・レコードに返された行からTIMESTAMP値pColValを取得するために、ttXlaColDesc_t構造体に返されたoffset値を使用していると想定しています。

TIMESTAMP_STRUCT timestamp;

rc = ttXlaTimeStampToODBCCType(pColVal, &timestamp);

---

ttXlaTableVersionVerify

説明

キャッシュされた表定義が、処理中のXLAレコードと互換性があること確認します。 列を追加または削除するためにALTER TABLEを使用する場合のみ表定義が変更されます。

トランザクション・タイプADDCOLSおよびDRPCOLSのXLAレコードのXLAストリームを監視すると、この関数の使用のオーバーヘッドを回避できます。トランザクション・タイプADDCOLSまたはDROPCOLSのXLAレコードが発生した場合は、表および列定義をリフレッシュします。 トランザクション・タイプのXLAレコードの監視の詳細は、「レコード・ヘッダーの確認および行アドレスの検出」を参照してください。

必要な権限

システム権限XLAが必要です。

構文

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

結果

キャッシュされた表定義が処理中のXLAレコードと互換性がある場合は、SQL_SUCCESSが返されます。返されない場合は、ttXlaErrorを使用してエラーをレポートします。

パラメータ

パラメータ	型	説明
handle	ttXlaHandle_h	データ・ストアのトランザクション・ログ・ハンドル。
table	ttXlaTblVerDesc_t *	キャッシュされた表記述。
record	ttXlaUpdateDesc_t *	処理する必要があるXLAレコード。
compat	out SQLINTEGER *	互換性情報を返します。 1: 表に互換性がある。 0: 表に互換性がない。

例

この例では、表の互換性を確認します。

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.
 */
}

参照

「ttXlaVersionColumnInfo」
「ttXlaVersionTableInfo」

---

ttXlaVersionColumnInfo

説明

変更更新XLAレコードの処理を必要とする表の列に関する情報を取得します。

必要な権限

システム権限XLAが必要です。

構文

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

結果

コールが成功すると、SQL_SUCCESSが返されます。返されない場合は、ttXlaErrorを使用してエラーをレポートします。

パラメータ

パラメータ	型	説明
handle	ttXlaHandle_h	データ・ストアのトランザクション・ログ・ハンドル。
record	ttXlaUpdateDesc_t *	処理する必要があるXLAレコード。
colinfo	out ttXlaColDesc_t *	maxcols列の記述を保持できる十分な大きさのバッファへのポインタ。
maxcols	SQLINTEGER	表に含めることができる列の最大数。この表にmaxcolsを超える列を含めると、エラーが返されます。
nreturned	out SQLINTEGER *	列の数が返されます。

例

この例では、次の定義を想定しています。

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

次のコールでは、最大20の列の記述が取得されます。

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

---

ttXlaVersionCompare

説明

2つのXLAバージョンを比較し、結果を返します。

必要な権限

システム権限XLAが必要です。

構文

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

パラメータ

パラメータ	型	説明
handle	ttXlaHandle_h	データ・ストアのトランザクション・ログ・ハンドル。
version1	ttXlaVersion_t *	version2と比較するXLAのバージョン。
version2	ttXlaVersion_t *	version1と比較するXLAのバージョン。
comparison	out SQLINTEGER *	比較結果。 0: version1とversion2が一致している。 -1: version1がversion2より古い。 +1: version1がversion2より新しい。

結果

コールが成功すると、SQL_SUCCESSが返されます。返されない場合は、ttXlaErrorを使用してエラーをレポートします。

例

XLAのconfiguredバージョンとactualバージョンを比較するには、次のコールを実行します。

ttXlaVersion_t configured, actual;
SQLINTEGER comparision;

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

注意

XLAベースのレプリケーションで2つのシステムを接続する場合は、次の手順を実行することをお薦めします。

1. プライマリ・サイトで、ttXlaGetVersionを使用してXLAバージョンを取得します。このバージョン情報をスタンバイ・サイトに送信します。

2. スタンバイ・サイトで、ttXlaGetVersionを使用してXLAバージョンを取得します。 ttXlaVersionCompareを使用して古いバージョンを判別します。2つのサイト間で適切な処理を行うには、古いバージョン番号を使用する必要があります。 ttXlaSetVersionを使用してスタンバイ・サイトで使用するインタフェースのバージョンを指定します。古いバージョン番号をプライマリ・サイトに返信します。

3. 選択したバージョンがプライマリ・サイトで受信された後、ttXlaSetVersionを使用して、使用するXLAのバージョンを指定します。

参照

「ttXlaGetVersion」
「ttXlaSetVersion」

---

ttXlaVersionTableInfo

説明

処理を必要とする変更更新レコードの表定義を取得します。表記述は、tableinfo出力パラメータに格納されます。

必要な権限

システム権限XLAが必要です。

構文

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

結果

コールが成功すると、SQL_SUCCESSが返されます。返されない場合は、ttXlaErrorを使用してエラーをレポートします。

パラメータ

パラメータ	型	説明
handle	ttXlaHandle_h	データ・ストアのトランザクション・ログ・ハンドル。
record	ttXlaUpdateDesc_t *	処理する必要があるXLAレコード。
tableinfo	out ttXlaTblVerDesc_t *	表定義に関する情報。

例

この例では、次の定義を想定しています。

ttXlaHandle_h xlahandle;
ttXlaUpdateDesc_t *record;
ttXlaTblVerDesc_t tabinfo;

次のコールでは、表定義が取得されます。

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

---

XLAで使用されるCデータ構造体

この項では、この章で説明されているXLA関数で使用されるCデータ構造体について説明します。 これらの構造体は、次のファイルで定義されています。

install_dir/include/tt_xla.h

XLAアプリケーションの作成時に、このファイルをインクルードする必要があります。

表9-1 Cデータ構造体の概要

Cデータ構造体	説明
ttXlaNodeHdr_t	レコード・タイプについて記述します。XLAによって返されるレコードの先頭で使用されます。
ttXlaUpdateDesc_t	更新レコードについて記述します。
ttXlaStatus_t	ttXlaStatusによって返されるXLAのステータス情報について記述します。
ttXlaVersion_t	ttXlaGetVersionによって返されるXLAのバージョン情報について記述します。
ttXlaTblDesc_t	ttXlaGetTableInfoによって返される表情報について記述します。
ttXlaTblVerDesc_t	ttXlaVersionTableInfoによって返される表バージョンについて記述します。
ttXlaColDesc_t	ttXlaGetColumnInfoによって返される表の列情報について記述します。
tt_LSN_t	ブックマークで使用されるログ・レコード識別子の記述です。この構造体は、ttXlaUpdateDesc_t構造体によって使用されます。
tt_XlaLsn_t	XLAブックマークで使用されるログ・レコード識別子について記述します。

---

ttXlaNodeHdr_t

ほとんどCデータ構造体は、データのレコード・タイプおよび長さについて記述する標準ヘッダーで始まります。標準ヘッダーの型はttXlaNodeHdr_tです。

このヘッダーには、次のフィールドが含まれています。

フィールド	型	説明
nodeType	char	レコードのタイプ。 TTXLANHVERSION: バージョン TTXLANHUPDATE: 更新 TTXLANHTABLEDESC: 表記述 TTXLANHCOLDESC: 列記述 TTXLANHSTATUS: ステータス TTXLANHINVALID: 無効
byteOrder	char	レコードのバイト順序。 1: ビッグ・エンディアン 2: リトル・エンディアン
length	SQLUINTEGER	すべての添付ファイルを含むレコードの全長。

---

ttXlaUpdateDesc_t

この構造体は、データ・ストア内の単一行（またはタプル）への更新処理について記述します。 ttXlaNextUpdateまたはttXlaNextUpdateWait関数によって返される各更新レコードは、固定長ヘッダーttXlaUpdateDesc_tで始まり、その後に0（ゼロ）から2行のデータ・ストアからの行が続きます。行データはttXlaUpdateDesc_tヘッダーにレポートされたレコード・タイプによって異なります。

• COMMITONLYのレコードに行は含まれません。

• INSERTTUP、DELETETUPまたはSETREPLレコードには1行の行が含まれます。

• UPDATETUPレコードには2行の行が含まれ、更新前および更新後の行データがレポートされます。

• CREATAB、DROPTAB、CREAIND、DROPIND、CREATVIEW、DROPVIEW、CREATSEQ、DROPSEQ、ADDCOLS、DRPCOLS、SETTBLIおよびSETCOLIレコードには、特別な書式行が含まれています（「特別な更新データの書式」を参照）。

注意: 永続モードでは、SETREPL、SETTBLIおよびSETCOLIレコードは返されません。

flagsフィールドは、レコード更新の特別なオプションのビットマップです。

connIDフィールドは、更新を開始したODBC接続ハンドルを識別します。この値を使用すると、更新が同一の接続から行われたかどうかを確認できます。

個別のコミットXLAレコードは、ttApplicationContextプロシージャをコールした後にXLAレコードを生成する処理が行われない場合に生成されます。 ttApplicationContextプロシージャについては、「アプリケーション・コンテキストの受渡し」を参照してください。

注意

XLAは、次の通知を受信できません。

• 非マテリアライズド・ビューのCREATE VIEWまたはDROP VIEW

• 一時表のCREATE GLOBAL TEMPORARY TABLEまたはDROP TABLE

ALTER TABLE処理で生成可能なXLAレコードは、次のタイプのみです。

• ADDCOLSまたはDRPCOLS（列を追加または削除する場合）

• CREAINDまたはDROPIND（列の一意の属性を変更する場合）

順序の作成（CREATESEQ）と削除（DROPSEQ）はXLAで参照できますが、順序の増分は参照できません。

カスケード削除によるすべての削除およびエージングによる削除はXLAで参照できます。 削除がカスケードによるものか、またはエージングによるものかは、flagsの値（次の表を参照）で示されます。

ttXlaUpdateDesc_tによって定義される更新ヘッダーのフィールドは、次のとおりです。

フィールド	型	説明
header	ttXlaNodeHdr_t	標準データ・ヘッダー
type	SQLUSMALLINT	レコード・タイプ。 CREATAB: 表の作成 DROPTAB: 表の削除 CREAIND: 索引の作成 DROPIND: 索引の削除 CREATVIEW: ビューの作成 DROPVIEW: ビューの削除 CREATSEQ: 順序の作成 DROPSEQ: 順序の削除 ADDCOLS: 列の追加 DRPCOLS: 列の削除 SETREPL: 表のレプリケーション・ステータスの設定 SETTBLI: 表ユーザーIDの設定 SETCOLI: 列ユーザーIDの設定 TRUNCATE: 表の切捨て INSERTTUP: 挿入 UPDATETUP: 更新 DELETETUP: 削除 COMMITONLY: コミット
flags	SQLUSMALLINT	レコード更新での特別なオプション。 TT_UPDCOMMIT: 更新レコードがトランザクションの最後のレコードであることを示します（暗黙的コミット）。 TT_UPDFIRST: 更新レコードがトランザクションの最初のレコードであることを示します。 TT_UPDREPL: この更新が別のデータ・ストアからのXLA以外のTimesTenでレプリケートされた更新の結果であったことを示します。 TT_UPDCOLS: 最後に返された行に続く、行内の更新された列を示すリストの存在を示します。このリストは、SQLUSMALLINT値の配列で構成され、リストの最初は更新された列の数で、更新された列の列番号がそれに続きます。 たとえば、1番目および3番目の列が更新された場合、この配列は、使用されたUPDATE文に応じて(2, 1, 3)、(2, 3, 1)などになります。この配列は、すべてのUPDATETUPレコードに含まれます。 TT_UPDDEFAULT: 更新レコード（CREATABまたはADDCOLSのいずれか）にデフォルトの列値が含まれていることを示します。デフォルトの列は、設定されている場合、SQLUSMALLINT値の配列として示され、すべてのデフォルト値が連結された文字列がその後に続きます。配列内のSQLUSMALLINT値の数は、CREATABまたはADDCOLSレコード内の列の数と同じです。 TT_CASCDEL: XLA更新が、カスケード削除処理の一部として生成されたことを示します。 TT_AGING: XLA更新が、エージング処理の一部として生成されたことを示します。 特定の列の値が0（ゼロ）の場合は、その列にデフォルト値がないことを示します。 0（ゼロ）以外のすべての値のデフォルト値は文字列内で連結され、デフォルト値の長さを示す配列値の順序で示されます。 たとえば、デフォルト値がINTEGER型の1が含まれる列、デフォルトがない列、およびVARCHAR2(10)型のappleが含まれる列の3つの列は、(1,0,5)1appleとなります。 これらの各flagsビットの10進値は、次のとおりです。 （一部のフラグ値は内部使用専用です。） TT_UPDCOMMIT 1 TT_UPDFIRST 2 TT_UPDREPL 4 TT_UPDCOLS 8 TT_UPDDEFAULT 64 TT_CASCDEL 256 TT_AGING 512
contextOffset	SQLUINTEGER	アプリケーションによって指定されるコンテキスト値のオフセット。コンテキストがない場合、この値は0（ゼロ）です。 0（ゼロ）以外の値は、XLAレコードの先頭に対するコンテキストの相対位置を示します。
connID	SQLUBIGINT	トランザクションを所有している接続ID。
sysTableID	SQLUBIGINT	システムによって指定される、影響を受ける表の識別子。
userTableID	SQLUBIGINT	アプリケーションによって定義される、影響を受ける表の表ID。
tranID	SQLUBIGINT	システムによって指定される、読取り専用のトランザクション識別子。
LSN	tt_LSN_t	診断に使用される、この処理のトランザクション・ログ・レコード識別子。
tuple1	SQLUINTEGER	第1行（tuple）の長さまたは0（ゼロ）。
tuple2	SQLUINTEGER	第2行（tuple）の長さまたは0（ゼロ）。

注意: tt_LSN_tの、特にlogFileフィールドおよびlogOffsetフィールドの使用方法が以前のリリースとは異なる点に注意してください。これらのフィールドは、連続的に増加するLSNではなく、ログ・レコード識別子を参照します。 「tt_LSN_t」の注意を参照してください。

特別な更新データの書式

ttXlaTblDesc_tヘッダーの後には、更新レコードに含まれているデータが続きます。 この項では、特定のSQL処理に関連した特別な更新レコードのデータ書式について説明します。

CREATE TABLE

CREATE TABLEの場合、特別な行の値は、新しい表について記述するttXlaTblDesc_tレコードおよびその後に続く、各列について記述するttXlaColDesc_tレコードで構成されています。

ALTER TABLE

ALTER TABLEの場合、特別な行の値は、ttXlaDropTableTup_tまたはttXlaAddColumnTup_t値およびその後に続く、列について記述するttXlaColDesc_tレコードで構成されます。

ttXlaDropTableTup_t

DROP TABLE処理の場合、行の値は次のようになります。

フィールド	型	説明
tblName	char(31)	削除される表の名前。
tblOwner	char(31)	削除される表の所有者。

ttXlaTruncateTableTup_t

TRUNCATE TABLE処理の場合、行の値は次のようになります。

フィールド	型	説明
tblName	char(31)	切り捨てられる表の名前。
tblOwner	char(31)	切り捨てられる表の所有者。

ttXlaCreateIndexTup_t

CREATE INDEX処理の場合、行の値は次のようになります。

フィールド	型	説明
tblName	char(31)	索引が定義される表の名前。
tblOwner	char(31)	索引が定義される表の所有者。
ixName	char(31)	新しい索引の名前。
flag	char(31)	索引フラグ。 P = プライマリ F = 外部 R = 標準
nixcols	SQLUINTEGER	索引付けされる列の数。
ixColsSys	SQLUINTEGER(16)	システム番号を使用して索引付けされる列番号。
ixColsUser	SQLUINTEGER(16)	ユーザー定義の列IDを使用して索引付けされる列番号。
ixType	char	T = 範囲、H = ハッシュ。
ixUnique	char	U = 一意索引、N = 非一意索引。
pages	SQLUINTEGER	ハッシュ索引のページ数。

ttXlaDropindexTup_t

DROP INDEX処理の場合、行の値は次のようになります。

フィールド	型	説明
tblName	char(31)	索引が削除された表の名前。
tblOwner	char(31)	索引が削除された表の所有者。
ixName	char(31)	削除された索引の名前。

ttXlaAddColumnTup_t

列の追加の場合、行の値は次のようになります。

フィールド	型	説明
ncols	SQLUINTEGER	追加列の数。

この特別な行の後に、新しい列について記述するttXlaColDesc_tレコードが続きます。

ttXlaDropColumnTup_t

列の削除の場合、行の値は次のようになります。

フィールド	型	説明
ncols	SQLUINTEGER	削除された列の数。

この特別な行の後に、削除された列について記述するttXlaColDesc_tレコードの配列が続きます。

ttXlaCreateSeqTup_t

CREATE SEQUENCE処理の場合、行の値は次のようになります。

フィールド	型	説明
sqName	char(31)	順序の名前。
sqOwner	char(31)	順序の所有者。
cycle	char	順序番号ジェネレータが、最大値または最小値に達した後も番号の生成を続行するかどうかを指定します。値は次のとおりです。 1 = 循環する。 0 = 循環しない。
minval	SQLBIGINT	順序の最小値。
maxval	SQLBIGINT	順序の最大値。
incr	SQLBIGINT	順序番号間の増分。正の値は昇順、負の値は降順を示します。 降順の場合、値の範囲はmaxvalからminvalまでです。 昇順の場合、値の範囲はminvalからmaxvalまでです。

ttXlaDropSeqTup_t

DROP SEQUENCE処理の場合、行の値は次のようになります。

フィールド	型	説明
sqName	char(31)	順序の名前。
sqOwner	char(31)	順序の所有者。

ttXlaViewDesc_t

CREATE MATERIALIZED VIEW処理の場合、行の値は次のようになります。

フィールド	型	説明
vwName	char(31)	マテリアライズド・ビューの名前。
vwOwner	char(31)	マテリアライズド・ビューの所有者。
sysTableID	SQLUBIGINT	SYS.TABLESに格納されたシステム表ID。

ttXlaDropViewTup_t

マテリアライズド・ビューに対するDROP VIEW処理の場合、行の値は次のようになります。

フィールド	型	説明
vwName	char(31)	マテリアライズド・ビューの名前。
vwOwner	char(31)	マテリアライズド・ビューの所有者。

ttXlaSetTableTup_t

表IDの設定処理の場合、更新レコードの主要部分で以前に割り当てられたアプリケーション表識別子を使用し、アプリケーション表識別子の新しい値を次の特別な行に指定するように記述されます。

フィールド	型	説明
newID	SQLUBIGINT	新しいユーザー定義の表ID。

ttXlaSetColumnTup_t

列ID設定処理の場合、次の特別な行が記述されます。

フィールド	型	説明
oldUserColID	SQLUINTEGER	以前のユーザー定義の列ID値。
newUserColID	SQLUINTEGER	新しいユーザー定義の列ID値。
sysColID	SQLUINTEGER	システム列ID。

ttXlaSetStatusTup_t

表のレプリケーション・ステータスの変更の場合、次の特別な行が記述されます。

フィールド	型	説明
oldStatus	SQLUINTEGER	以前のレプリケーション・ステータス。
newStatus	SQLUINTEGER	新しいレプリケーション・ステータス。

ttXlaUpdateDesc_tヘッダーの後に続く行データのアドレスの検出

更新レコードを取得する手順およびttXlaUpdateDesc_tヘッダーの内容を確認する手順の詳細は、「トランザクション・ログからの更新レコードの取得」および「レコード・ヘッダーの確認および行アドレスの検出」を参照してください。次に、これらの手順の概要を示します。

更新ヘッダーの直後に行データが続きます。 行データは、ttXlaGetColumnInfoによって返されるttXlaColDesc_t構造体に指定されているオフセットとともに内部形式で格納されます。

更新ヘッダーのサイズにそのアドレスを追加して、行データのアドレスを検出することができます。

次に例を示します。

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

UPDATETUPレコードの場合、ttXlaUpdateDesc_tヘッダーの後に2行のデータが続きます。1つ目の行には更新前のデータ、2つ目の行には更新後のデータが含まれています。

新しい行は古い行の直後に続くため、古い行の長さ（tuple1）にそのアドレスを追加して、新しい行のアドレスを計算することができます。

次に例を示します。

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

返された行内の列データにアクセスする方法の詳細については、「ttXlaColDesc_t」を参照してください。

---

ttXlaStatus_t

ttXlaStatus_t構造体では、XLAシステムに関する実行時処理情報が示されます。非永続モードでXLAを処理する場合、この構造体はttXlaStatus関数によって返されます。

フィールド	型	説明
header	ttXlaNodeHdr_t	標準データ・ヘッダー。
xlabuffree	SQLUBIGINT	ステージング・バッファ内の空き領域（バイト）。
xlabufminfree	SQLUBIGINT	ステージング・バッファ内の最小空き領域（バイト）。
xlabufalloc	SQLUBIGINT	ステージング・バッファ内の割当て済領域（バイト）。
xlabuftran	SQLUBIGINT	ステージング・バッファ内のトランザクションの数。
xlabufrec	SQLUBIGINT	ステージング・バッファ内のレコードの数。
logbuffree	SQLUBIGINT	トランザクション・ログ・バッファ内の空き領域（バイト）。
logbufminfree	SQLUBIGINT	トランザクション・ログ・バッファ内の最小空き領域（バイト）。
logbufalloc	SQLUBIGINT	トランザクション・ログ・バッファ内の割当て済領域（バイト）。
flags	SQLUINTEGER	ステータス・フラグのビットマップ。現在、TTXLASTAT_STALLED のみが定義されています。このフラグが設定されると、XLAステージング・バッファがいっぱいで新しい更新が拒否されていることを示します。

---

ttXlaVersion_t

XLAを将来拡張できるように、バージョン構造体ttXlaVersion_tに、現在のXLAのバージョンおよび構造体のバイト順序が記述されています。この構造体はttXlaGetVersion関数によって返されます。

この構造体には、次のフィールドが含まれています。

フィールド	型	説明
header	ttXlaNodeHdr_t	標準データ・ヘッダー。
hardware	char (16)	ハードウェア・プラットフォームの名前。
wordSize	SQLUINTEGER	システム固有のワード・サイズ（32または64）。
TTMajor	SQLUINTEGER	TimesTenバージョン番号。
TTMinor	SQLUINTEGER	TimesTenリリース番号。
TTPatch	SQLUINTEGER	TimesTenポイント・リリース番号。
OS	char (16)	オペレーティング・システムの名前。
OSMajor	SQLUINTEGER	オペレーティング・システムのバージョン番号。
OSMinor	SQLUINTEGER	オペレーティング・システムのリリース番号。

---

ttXlaTblDesc_t

表情報は、ttXlaTblDesc_t構造体を使用して表現されます。 この構造体は、ttXlaGetTableInfo関数によって返されます。

この構造体には、次のフィールドが含まれています。

フィールド	型	説明
header	ttXlaNodeHdr_t	標準データ・ヘッダー。
tblName	char (31)	表の名前（空文字で終了）。
tblOwner	char (31)	表の所有者（空文字で終了）。
sysTableID	SQLUBIGINT	一意のシステム定義識別子。
userTableId	SQLUBIGINT	ユーザー定義表識別子。
columns	SQLUINTEGER	列の数。
width	SQLUINTEGER	インライン行のサイズ。
nPrimCols	SQLUINTEGER	プライマリ列の数。
primColsSys	SQLUINTEGER(16)	システム主キー列番号。
primColsUser	SQLUINTEGER(16)	ユーザー定義主キー列番号。

インライン行のサイズには、すべての固定長列、NULL列フラグ、および可変長列のポインタ情報のためのスペースが含まれています。 可変長列ごとに、4バイトのインライン行領域が使用されます。

表に宣言済の主キーがある場合は、次の点に注意してください。

• nprimcolsは0（ゼロ）より大きくなります。

• primcolsSys配列には、最初にCREATE TABLE文で宣言した順序と同じ順序で主キーの列番号が含まれます。

• primcolsUser配列には、対応するアプリケーション指定の列識別子が含まれます。

---

ttXlaTblVerDesc_t

このデータ構造体には、表のバージョン番号とttXlaTblDesc_tが含まれています。この構造体はttXlaVersionTableInfoによって返されます。この構造体には、次のフィールドが含まれています。

フィールド	型	説明
tblDesc	ttXlaTblDesc_t	表記述
tblVer	SQLBIGINT	システム生成表のバージョン番号。

---

ttXlaColDesc_t

列情報は、ttXlaColDesc_t構造体を使用して提供されます。 この構造体は、ttXlaGetColumnInfo関数によって返されます。

この構造体には、次のフィールドが含まれています。

フィールド	型	説明
header	ttXlaNodeHdr_t	標準データ・ヘッダー。
colName[tt_NameLenMax]	char	列の名前。
pad0	SQLUINTEGER	4バイト境界まで埋め込みます。
sysColNum	SQLUINTEGER	列番号（1から始まります）。
userColNum	SQLUINTEGER	ユーザー割当ての列番号。
dataType	SQLUINTEGER	ODBC TTXLA_*コードの構造体。 「XLAデータ型について」を参照してください。
size	SQLUINTEGER	列の最大サイズまたは基本サイズ。
offset	SQLUINTEGER	列の固定長部分に対するオフセット。
nullOffset	SQLUINTEGER	NULLバイトに対するオフセット（NULL値可能でない場合は0（ゼロ）です）。
precision	SQLSMALLINT	DECIMAL型の数値の精度。
scale	SQLSMALLINT	DECIMAL型の数値のスケール。
flags	SQLUINTEGER	列フラグ。 TT_COLPRIMKEY: 列は主キーです。 TT_COLVARYING: 列はアウトラインで格納されています。 TT_COLNULLABLE: 列はNULL値可能です。 TT_COLUNIQUE: 列に一意の属性が定義されています。

ttXlaColDesc_t構造体を取得する手順およびその内容を確認する手順は、「列データの確認」を参照してください。次に、これらの手順の概要を示します。

ttXlaColDesc_t構造体は、ttXlaGetColumnInfo関数によって返されます。この構造体には、特定の表の列情報にアクセスするために必要なメタデータが格納されています。 たとえば、offsetフィールドを使用すると、ttXlaColDesc_t構造体の後の更新レコードに返された行（一行または複数行）の特定の列データを検出できます。列値のアドレスは、返された行のアドレスにoffsetを追加して検出することができます。 その後、dataTypeフィールドに基づいてこの値を対応するC型にキャストしたり、「複合データ型の変換」で説明されている変換ルーチンの1つに渡すことができます。

TimesTenの行データは、固定長データおよびその後に続く可変長データで構成されます。

• 固定長列データの場合、ttXlaColDesc_tは列データのoffsetおよびsizeを返します。 offsetはレコードの固定部分の先頭に関連しています。例9-1を参照してください。

• 可変長列データ（VARCHARおよびVARBINARY）の場合、offsetは4バイトのオフセット値を指すアドレスです。オフセット・アドレスをオフセット値に追加すると、行の可変長部分の列データのアドレスを取得できます。この場所の最初のnバイトはデータの長さで、その後に実際のデータが続きます（nは、32ビットのプラットフォームでは4、64ビットのプラットフォームでは8です）。 可変長データの場合、返されるsize値は列の許容最大サイズです。例9-1を参照してください。

NULL値が含まれる可能性がある列の場合、nullOffsetはレコードのNULLバイトを指します。 この値は、列がNULLの場合は1、NULLでない場合は0（ゼロ）になります。 詳細は、「NULL値の検出」を参照してください。

flagsビットは、列がNULL値可能であるかどうか、主キーの一部となるかどうか、またはアウトラインで格納されるかどうかを定義します。

sysColNum値は、列に割り当てるシステム列番号です。この値は、最初の列に対しては1から始まります。

例9-1 VARCHAR文字列のコピーと出力

固定長列データの場合、列のアドレスは、次のようにttXlaColDesc_t構造体のoffset値に行のアドレスを追加したものです。

ttXlaColDesc_t colDesc;

void* pColVal = colDesc->offset + row;

列の値は、データ型に対応する型ポインタを使用してこのポインタを参照解除すると取得できます。 たとえば、SQL_INTEGERの場合、ODBC型はSQLINTEGERであるため、列の値は次のように入力すると取得できます。

*((SQLINTEGER*) pColVal))

可変長列データの場合、前述の手順で計算されたpColValは4バイトのオフセット値のアドレスになります。このオフセット値をpColValのアドレスに追加すると、可変長列データの先頭を指すポインタが示されます。 64ビットのプラットフォームで処理が行われると想定すると、この場所の最初の8バイトはこのデータの長さ（var_len）で、その後に実際のデータ（var_data）が続きます。

この例では、VARCHAR文字列をコピーおよび出力します。

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

ブックマークで使用されるログ・レコード識別子の記述です。この構造体は、ttXlaUpdateDesc_t構造体によって使用されます。

フィールド	型	説明
logFile	SQLUBIGINT	ログ・レコード識別子の上位部分。
logOffset	SQLUBIGINT	ログ・レコード識別子の下位部分。

注意: logFileおよびlogOffsetフィールド名は、下位互換性を保つために保持されていますが、使用方法は変更されています。以前のリリースでは、値は連続的に増加するLSNを参照していました。また、この値は具体的な意味を持ち、ログ・ファイル番号とバイト・オフセットを表していました。現在ではログ・レコード識別子を参照します。この識別子は、より抽象的で、ログ・ファイル番号やバイト・オフセットとは直接関係しません。ログ・レコード識別子の順序に関して想定できることは、ログ・レコード識別子Aよりも後に読み取られたログ・レコード識別子Bは、より大きい値を持つということのみです。

---

tt_XlaLsn_t

ブックマークで使用されるログ・レコード識別子の記述です。 この構造体はttXlaGetLSN関数によって返され、ttXlaSetLSN関数によって使用されます。

checksumはXLAハンドル固有であり、すべてのログ・レコード識別子が特定のXLA接続と関連付けられていることを保証します。

フィールド	型	説明
checksum	SQLUINTEGER	有効なログ・レコード識別子ハンドルであることを保証するためのチェックサム。
xid	SQLUSMALLINT	トランザクションID。
logFile	SQLUBIGINT	ログ・レコード識別子の上位部分。
logOffset	SQLUBIGINT	ログ・レコード識別子の下位部分。

注意: logFileおよびlogOffsetフィールド名は、下位互換性を保つために保持されていますが、使用方法は変更されています。以前のリリースでは、値は連続的に増加するLSNを参照していました。また、この値は具体的な意味を持ち、ログ・ファイル番号とバイト・オフセットを表していました。現在ではログ・レコード識別子を参照します。この識別子は、より抽象的で、ログ・ファイル番号やバイト・オフセットとは直接関係しません。ログ・レコード識別子の順序に関して想定できることは、ログ・レコード識別子Aよりも後に読み取られたログ・レコード識別子Bは、より大きい値を持つということのみです。