9 XLAリファレンス

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

• 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をコールするまで有効なままです。

• ttXlaAcknowledgeの場合、アプリケーションでバッファへのアクセスを長時間維持する必要がある場合は、XLAによって返されるバッファの情報をアプリケーション専用のバッファにコピーする必要があります。

実際の列値を除き、XLA内の文字列値は空文字で終了します。固定長の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コア関数を示しますが、データ型変換関数に関してはこの後の表に別にリストしています。

関数	説明
ttXlaAcknowledge	1つ以上のトランザクション更新レコードをトランザクション・ログから取得したことを確認します。
ttXlaClose	ttXlaPersistOpenによってオープンされたXLAハンドルをクローズします。
ttXlaConvertCharType	列データを接続キャラクタ・セットに変換します。
ttXlaDeleteBookmark	トランザクション・ログ・ブックマークを削除します。
ttXlaError	エラー情報を取得します。
ttXlaErrorRestart	エラー・スタック情報をリセットします。
ttXlaGetColumnInfo	表内のすべての列に関する情報を取得します。
ttXlaGetLSN	データベースの現在のブックマークのログ・レコード識別子を取得します。
ttXlaGetTableInfo	表に関する情報を取得します。
ttXlaGetVersion	XLAの現行のバージョンを取得します。
ttXlaNextUpdate	TimesTenから一連の更新を取得します。
ttXlaNextUpdateWait	TimesTenから一連の更新を取得します。使用可能な更新がトランザクション・ログにない場合は、指定した時間待機します。
ttXlaPersistOpen	トランザクション・ログにアクセスするためにデータベースへのハンドルを初期化します。
「ttXlaSetLSN」	データベースの現在のブックマークのログ・レコード識別子を設定します。
ttXlaSetVersion	使用するXLAのバージョンを設定します。
ttXlaTableByName	所有者および名前が指定された表のシステム表識別子およびユーザー表識別子を検出します。
ttXlaTableStatus	表の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レプリケーション関数

『Oracle TimesTen In-Memory Database開発者および管理者ガイド』に記載されているとおり、TimesTenのレプリケーションは、ほとんどの顧客要件を満たすには十分ですが、XLA関数を使用して、1つのデータベースから別のデータベースに更新をレプリケートすることもできます。この方法で独自のレプリケーション・スキームをXLAの上に実装することはかなり困難ですが、TimesTenのレプリケーションがなんらかの理由で実行できない場合には検討できます。

次の表に、レプリケーション・メカニズムとしてXLAのみを使用する関数を示します。(これらの関数についてのリファレンス情報は、他のXLA関数に関する別の項の「XLAレプリケーション関数参照」を参照してください。)

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

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

XLA関数リファレンス

この項では、XLAコア関数およびXLAデータ型変換関数のリファレンス情報を示します。関数は、アルファベット順に示されています。

注意: レプリケーション・メカニズムとしてXLAのみで使用される関数については、別の項(「XLAレプリケーション関数参照」)を参照してください。

ttXlaAcknowledge

説明

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

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

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

ttXlaAcknowledgeは、必要な場合にのみ使用する必要がある高コストの処理です。XLAではトランザクション・ログ・ファイルが一度に1つしかパージされないため、トランザクション・ログ・ファイルを読み取るたびにttXlaAcknowledgeを複数回コールしても、トランザクション・ログのボリュームは減少しません。新しいトランザクション・ログ・ファイルの生成を検出するには、システム表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

ttXlaClose

説明

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

必要な権限

XLA

構文

SQLRETURN ttXlaClose(ttXlaHandle_h handle)

パラメータ

パラメータ	型	説明
handle	ttXlaHandle_h	データベースのODBCハンドル

結果

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

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

rc = ttXlaClose(xlahandle);

関連項目

ttXlaPersistOpen

ttXlaConvertCharType

説明

colinfoパラメータおよびtupパラメータで示されている列データを、トランザクション・ログ・ハンドルに関連付けられている接続キャラクタ・セットに変換し、結果をバッファに格納します。

必要な権限

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	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	char*	変換された文字列を保持するように割り当てられた記憶域へのポインタ
precision	SQLSMALLINT	fromDataが1より大きい場合は、小数点をはさんだ最大桁数 fromDataが1より小さい場合は、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

説明

指定したトランザクション・ログ・ハンドルに関連付けられているブックマークを削除します。ブックマークは削除するとアクセスできなくなり、ブックマークの識別子は別のブックマークで再利用できます。ブックマークを削除すると、データベース・ハンドルとの関連が失われ、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

説明

特定のトランザクション・ログ・ハンドルに対して以前コールした際に発生したエラーの詳細をレポートします。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	SQLINTEGER*	errMessageバッファにコピーされるエラー・メッセージのコード
errMessage	char*	エラー・テキストが保持されるバッファ
maxLen	SQLINTEGER	errMessageバッファの最大長
retLen	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

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	ttXlaColDesc_t*	maxcols列の個別の記述を保持できる十分な大きさのバッファへのポインタ
maxcols	SQLINTEGER	colInfoバッファに格納可能な列の最大数 この表にmaxcolsを超える列を含めると、エラーが返されます。
nreturned	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

説明

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

必要な権限

XLA

構文

SQLRETURN ttXlaGetLSN(ttXlaHandle_h handle,
                      out 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 = 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	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が新しいバージョンです。

この関数は、現在構成されている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	ttXlaVersion_t*	構成されているXLAのバージョン
actualVersion	ttXlaVersion_t*	XLAの実際のバージョン

結果

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

例

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

ttXlaVersion_t configured, actual;

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

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

関連項目

「ttXlaVersionCompare」
「ttXlaSetVersion」

ttXlaNextUpdate

説明

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

ttXlaNextUpdateをコールするたびに、最後に読み取られたレコードにブックマークが再設定され、次のレコードのリストを返すためにttXlaNextUpdateへの次のコールが有効にされます。

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

必要な権限

XLA

構文

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

パラメータ

パラメータ	型	説明
handle	ttXlaHandle_h	データベースのトランザクション・ログ・ハンドル
record	ttXlaUpdateDesc_t***	完了したトランザクション・レコードを保持するバッファ
maxrecords	SQLINTEGER	フェッチされるレコードの最大数
nreturned	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	ttXlaUpdateDesc_t***	完了したトランザクション・レコードを保持するバッファ
maxrecords	SQLINTEGER	フェッチされるレコードの最大数 注意: 有効な最大値は1000レコードです。
nreturned	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の大きさが十分であると想定される場合は、書き込まれたバイト数(十分でない場合は、書き込まれたはずのバイト数)

結果

コールが成功した場合は、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を使用してエラーをレポートします。

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 Database 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 Database TIMESTAMP値から変換されたODBCタイムスタンプ値

結果

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

ttXlaPersistOpen

説明

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

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

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

• ttXlaAcknowledge

• ttXlaGetLSN

• 「ttXlaSetLSN」

• ttXlaNextUpdate

• ttXlaNextUpdateWait

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

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

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

注意: このコールによって領域が割り当てられます。終了後にttXlaCloseをコールして、領域を解放します。

必要な権限

XLA

構文

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

パラメータ

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

結果

コールが成功した場合は、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」

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

説明

トランザクション・ログ・ハンドルで指定されたデータベースの現行読取りログ・レコード識別子を設定します。指定する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」

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	SQLUBIGINT*	システム表ID
userTableID	SQLUBIGINT*	ユーザー表ID

結果

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

例

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

SQLUBIGINT sysTableID;
SQLUBIGINT userTableID;

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

関連項目

ttXlaTableStatus

ttXlaTableStatus

説明

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

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

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

ttXlaTableStatusを使用するには、ユーザーはブックマークに接続する必要があります。この関数では、挿入、更新および削除を、表にサブスクライブしたブックマークにのみレポートします。DDLイベントがすべてのブックマークにレポートされます。DDLイベントには、CREATAB、DROPTAB、CREAIND、DROPIND、CREATVIEW、DROPVIEW、CREATSEQ、DROPSEQ、CREATSYN、DROPSYN、ADDCOLS、DRPCOLS、TRUNCATE、SETTBL1およびSETCOL1トランザクションが含まれています。これらのイベント・タイプの詳細は、「ttXlaUpdateDesc_t」を参照してください。

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

注意: XLAを介して追跡される表へのDML更新では、ttXlaTableStatusの実行を妨げません。ただし、追跡される表へのDDL更新ではSYS.TABLESがロックされるため、SYS.TABLESに対するシリアライズ可能分離レベルでのttXlaTableStatusの実行が遅延します。

必要な権限

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

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)

パラメータ

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

結果

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

例

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

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

ttXlaTimeToODBCCType

説明

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

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

必要な権限

XLA

構文

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

パラメータ

パラメータ	型	説明
fromData	void*	トランザクション・ログから返されたTIME値へのポインタ
returnData	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	TIMESTAMP_STRUCT*	変換されたタイムスタンプを保持するように割り当てられた記憶域へのポインタ

結果

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

例

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

TIMESTAMP_STRUCT timestamp;

rc = ttXlaTimeStampToODBCCType(pColVal, &timestamp);

ttXlaVersionColumnInfo

説明

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

必要な権限

XLA

構文

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

パラメータ

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

結果

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

例

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

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のバージョン
比較	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)

パラメータ

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

結果

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

例

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

ttXlaHandle_h xlahandle;
ttXlaUpdateDesc_t* record;
ttXlaTblVerDesc_t tabinfo;

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

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

XLAレプリケーション関数参照

『Oracle TimesTen In-Memory Database開発者および管理者ガイド』に記載されているとおり、TimesTenのレプリケーションは、ほとんどの顧客要件を満たすには十分ですが、XLA関数を使用して、1つのデータベースから別のデータベースに更新をレプリケートすることもできます。この方法で独自のレプリケーション・スキームをXLAの上に実装することはかなり困難ですが、TimesTenのレプリケーションがなんらかの理由で実行できない場合には検討できます。

この項では、レプリケーション・メカニズムとしてXLAのみを使用する関数について説明します。関数は、アルファベット順に示されています。

ttXlaApply

この関数はXLAレプリケーション機能の一部であり、一般的なXLAアプリケーションでの使用には適していません。

説明

トランザクション・ログ・ハンドルに関連付けられているデータベースに更新を適用します。戻り値は、更新が成功したかどうかを示します。また、更新によって永続的な問題が発生したかどうかも示します。(更新で一時的な問題(デッドロック、タイムアウトなど)が発生したかどうかを確認するには、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文を生成するトランザクション
テスト	SQLINTEGER	古い値のテスト: 1: テストは有効 0: テストは無効

結果

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

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

例

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

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

注意

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

関連項目

ttXlaCommit
ttXlaRollback
ttXlaLookup
ttXlaTableCheck
ttXlaGenerateSQL

ttXlaCommit

この関数はXLAレプリケーション機能の一部であり、一般的なXLAアプリケーションでの使用には適していません。

説明

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

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

必要な権限

XLA

構文

SQLRETURN ttXlaCommit(ttXlaHandle_h handle)

パラメータ

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

結果

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

例

rc = ttXlaCommit(xlahandle);

関連項目

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

ttXlaGenerateSQL

この関数はXLAレプリケーション機能の一部であり、一般的なXLAアプリケーションでの使用には適していません。

注意: この関数は、現在はLOBロケータでは動作しません。

説明

更新レコードの結果を示すSQL DMLまたはDDL文を生成します。生成された文は、データベースには適用されません。かわりに、文は、最大サイズがmaxLenパラメータによって指定される特定のバッファに返されます。バッファの実際のサイズは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	char*	変換されたSQL文の場所
maxLen	SQLINTEGER	バッファの最大長(バイト)
actualLen	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」

ttXlaLookup

この関数はXLAレプリケーション機能の一部であり、一般的なXLAアプリケーションでの使用には適していません。

説明

この関数は、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*	検索する表
キー	void*	表に対して定義された構造内のレコード 表の主キーの一部であるキー・レコードの列のみが調べられます。
result	void*	検出されたレコードのコピー先 一致するキー列を持つレコードが存在しない場合は、エラーが返されます。
maxsize	SQLINTEGER	resultバッファに格納可能な最大レコードのサイズ
retsize	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」

ttXlaRollback

この関数はXLAレプリケーション機能の一部であり、一般的なXLAアプリケーションでの使用には適していません。

説明

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

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

必要な権限

XLA

構文

SQLRETURN ttXlaRollback(ttXlaHandle_h handle)

パラメータ

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

結果

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

例

rc = ttXlaRollback(xlahandle);

関連項目

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

ttXlaTableCheck

この関数はXLAレプリケーション機能の一部であり、一般的なXLAアプリケーションでの使用には適していません。

説明

レプリケーション・メカニズムとしてXLAを使用する場合、この関数は、マスター・データベースから受信したttXlaTblDesc_t構造体内の名前付き表が、トランザクション・ログ・ハンドルに関連付けられているサブスクライバ・データベースまたはデータベースと互換性があることを検証します。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	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」

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

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

install_dir/include/tt_xla.h

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

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

Cデータ構造体	説明
ttXlaNodeHdr_t	レコード・タイプについて記述します。XLAによって返されるレコードの先頭で使用されます。
ttXlaUpdateDesc_t	更新レコードについて記述します。
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には1つの行があります。

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

• CREATAB、DROPTAB、CREAIND、DROPIND、CREATVIEW、DROPVIEW、CREATSEQ、DROPSEQ、CREATSYN、DROPSYN、ADDCOLSおよびDRPCOLSレコードには特別な書式行があります(「特別な更新データの書式」を参照)。

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: 順序の削除。 CREATSYN: シノニムの作成。 DROPSYN: シノニムの削除。 ADDCOLS: 列の追加。 DRPCOLS: 列の削除。 TRUNCATE: 表の切捨て。 INSERTTUP: 挿入。 UPDATETUP: 更新。 DELETETUP: 削除。 COMMITONLY: コミット。
フラグ	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)	新しい索引の名前
フラグ	char(31)	索引フラグ。 P: 主キー F: 外部キー R: 標準
nixcols	SQLUINTEGER	索引付けされる列の数
ixColsSys	SQLUINTEGER(16)	システム番号を使用して索引付けされる列番号
ixColsUser	SQLUINTEGER(16)	ユーザー定義の列IDを使用して索引付けされる列番号
ixType	char	索引のタイプ。 T: 範囲 H: ハッシュ B: ビットマップ
ixUnique	char	索引の一意性。 U: 一意 N: 一意でない
ページ	SQLUINTEGER	ハッシュ索引のページ数

ttXlaDropIndexTup_t

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

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

ttXlaAddColumnTup_t

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

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

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

ttXlaDropColumnTup_t

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

フィールド	型	説明
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 VIEW処理の場合、行の値は次のようになります。

注意: これは、マテリアライズド・ビューおよび非マテリアライズド・ビューのどちらにも適用されます。

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

ttXlaDropViewTup_t

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

注意: これは、マテリアライズド・ビューおよび非マテリアライズド・ビューのどちらにも適用されます。

フィールド	型	説明
vwName	char(31)	ビューの名前
vwOwner	char(31)	ビューの所有者

ttXlaCreateSynTup_t

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

フィールド	型	説明
synName	char(31)	シノニムの名前
synOwner	char(31)	シノニムの所有者
objName	char(31)	シノニムが指すオブジェクトの名前
objOwner	char(31)	シノニムが指すオブジェクトの所有者
isPublic	char	シノニムがパブリックかどうかを示します。 1: True 0: False
isReplace	char	シノニムがCREATE OR REPLACEを使用して作成されたかどうかを示します。 1: True 0: False

ttXlaDropSynTup_t

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

フィールド	型	説明
synName	char(31)	シノニムの名前
synOwner	char(31)	シノニムの所有者
isPublic	char	シノニムがパブリックかどうかを示します。 1: True 0: False

ttXlaSetTableTup_t

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

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

ttXlaSetColumnTup_t

SET COLUMN 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」を参照してください。

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

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

この構造体には、次のフィールドがあります。

フィールド	型	説明
header	ttXlaNodeHdr_t	標準データ・ヘッダー
colName [tt_NameLenMax]	char	列の名前
pad0	SQLUINTEGER	4バイト境界まで埋込み
sysColNum	SQLUINTEGER	表の作成時またはその後の変更時に決定された列の序数 SYS.COLUMNSの対応するCOLNUM値と同じです。(『Oracle TimesTen In-Memory Databaseシステム表およびビュー・リファレンス』のSYS.COLUMNSに関する説明を参照してください。)
userColNum	SQLUINTEGER	列の序数(オプションでユーザーが指定した場合) これは、0(ゼロ)またはttSetUserColumnID TimesTen組込みプロシージャで指定した列番号です。(『Oracle TimesTen In-Memory Databaseリファレンス』のttSetUserColumnIDに関する説明を参照してください。)
dataType	SQLUINTEGER	ODBC TTXLA_*コードの構造体 「XLAデータ型について」を参照してください。
size	SQLUINTEGER	列の最大または基本サイズ
offset	SQLUINTEGER	列の固定長部分に対するオフセット
nullOffset	SQLUINTEGER	NULLバイトに対するオフセット、またはNULL値可能でない場合は0(ゼロ)
precision	SQLSMALLINT	DECIMAL型の数値の精度
scale	SQLSMALLINT	DECIMAL型の数値のスケール
フラグ	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を参照してください。

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

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

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

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

注意: XLAでのLOBのサポートは、次のように制限されています。 LOB列を含む表にサブスクライブできますが、LOB値自体についての情報は使用できません。 ttXlaGetColumnInfoでは、LOB列に関する情報が返されます。 LOBを含む列は、空(長さがゼロ)またはNULL(実際に値がNULLの場合)としてレポートされます。このようにして、NULL列と非NULL列を区別できます。

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

固定長列データの場合、列のアドレスは、次のように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は、より大きい値を持つということのみです。