この章では、第5章「XLAおよびTimesTenイベント管理」で説明したトランザクション・ログAPI(XLA)のリファレンス情報を示します。内容は次のとおりです。
この項では、TimesTen ClassicのXLA機能に関する一般情報について説明します。
この章で説明するすべてのXLA API関数は、SQLRETURN
型の値を返しますが、この値は、ODBCによって次のいずれかの値になるように定義されています。
SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_NO_DATA_FOUND
SQL_ERROR
XLAエラーの処理方法については、「XLAエラーの処理」を参照してください。
ノート: SQL_NO_DATA_FOUND は、sqlext.h (timesten.h に含まれています)に定義されています。 |
関数の説明では、次のことに注意してください。
特に示されていないかぎり、すべてのパラメータは入力専用です。
出力パラメータには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
が必要になります。
TimesTen XLAは、TimesTen Classicデータベースへの更新を検出するために使用したり、独自のレプリケーション・ソリューションを構築するツールキットとして使用できます(第5章「XLAおよびTimesTenイベント管理」を参照)。
この項では、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イベント・ハンドラ・アプリケーションの作成」を参照してください。
次の表に、データ型変換関数を示します。
関数 | 説明 |
---|---|
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データ型について」を参照してください。
『Oracle TimesTen In-Memory Databaseレプリケーション・ガイド』に記載されているとおり、TimesTenのレプリケーションは、ほとんどのTimesTen顧客要件を満たすには十分ですが、XLA関数を使用して、1つのデータベースから別のデータベースに更新をレプリケートすることもできます。この方法で独自のレプリケーション・スキームをXLAの上に実装することはかなり困難ですが、TimesTenのレプリケーションがなんらかの理由で実行できない場合には検討できます。
次の表に、レプリケーション・メカニズムとしてXLAのみを使用する関数を示します。(これらの関数についてのリファレンス情報は、他のXLA関数に関する別の項の「XLAレプリケーション関数参照」を参照してください。)
関数 | 説明 |
---|---|
ttXlaApply |
XLAハンドルに関連付けられているデータベースに更新を適用します。 |
ttXlaCommit |
トランザクションをコミットします。 |
ttXlaGenerateSQL |
更新レコードの結果を示すSQL文を生成します。 |
ttXlaLookup |
特定のキー値を持つ表の更新レコードを検索します。 |
ttXlaRollback |
トランザクションをロールバックします。 |
ttXlaTableCheck |
送信側のデータベースから受信した表記述内の指定した表が、受信側のデータベースと互換性があることを検証します。 |
これらの関数の使用方法については、「レプリケーション・メカニズムとしてのXLAの使用」を参照してください。
この項では、XLAコア関数およびXLAデータ型変換関数のリファレンス情報を示します。関数は、アルファベット順に示されています。
説明
この関数は、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
をコールしてブックマークの位置を現在のレコードに再設定します。
この関数の使用方法については、「トランザクション・ログからの更新レコードの取得」を参照してください。
結果
コールが成功した場合は、SQL_SUCCESS
が返されます。返されない場合は、ttXlaError
を使用してエラーをレポートします。
前述の例でオープンしたXLAハンドルをクローズするには、次のコールを実行します。
rc = ttXlaClose(xlahandle);
構文
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 |
変換されたデータが格納されるバッファのサイズ |
説明
TTXLA_DATE_TT
値を、アプリケーションで使用可能なODBC C値に変換します。この関数の使用方法については、「複合データ型の変換」を参照してください。
この関数は、TTXLA_DATE_TT
データ型の列に対してのみコールします。データ型は、ttXlaGetColumnInfo
関数によって返されるttXlaColDesc_t
構造体から取得できます。
説明
TTXLA_DECIMAL_TT
値を、アプリケーションで使用可能な文字列に変換します。scaleおよびprecisionの値は、ttXlaGetColumnInfo
関数によって返されるttXlaColDesc_t
構造体から取得できます。scale
パラメータは、小数点以下の最大桁数を指定します。DECIMAL値が1より大きい場合、precision
パラメータは小数点をはさんだ最大桁数を指定します。DECIMAL値が1より小さい場合、precision
はscale
と同じになります。
この関数は、TTXLA_DECIMAL_TT
型の列に対してのみコールします。データ型は、ttXlaGetColumnInfo
関数によって返されるttXlaColDesc_t
構造体から取得できます。
この関数の使用方法については、「複合データ型の変換」を参照してください。
構文
SQLRETURN ttXlaDecimalToCString(void* fromData, out char* returnData, SQLSMALLINT precision, SQLSMALLINT scale)
パラメータ
パラメータ | 型 | 説明 |
---|---|---|
fromData |
void* |
トランザクション・ログから返されたDECIMAL値へのポインタ |
returnData |
char* |
変換された文字列を保持するように割り当てられた記憶域へのポインタ |
precision |
SQLSMALLINT |
fromData が1より大きい場合は、小数点をはさんだ最大桁数
|
scale |
SQLSMALLINT |
小数点以下の最大桁数 |
例
この例では、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);
説明
指定したトランザクション・ログ・ハンドルに関連付けられているブックマークを削除します。ブックマークは削除するとアクセスできなくなり、ブックマークの識別子は別のブックマークで再利用できます。ブックマークを削除すると、データベース・ハンドルとの関連が失われ、XLANONE
オプションを指定して接続をオープンした場合と同じ結果になります。
ブックマークを使用している場合は、不要になるまで削除できません。
この関数の使用方法については、「ブックマークの削除」を参照してください。
ノート:
|
説明
特定のトランザクション・ログ・ハンドルに対して以前コールした際に発生したエラーの詳細をレポートします。ttXlaError
への後続のコールで、複数のエラーが返される場合があります。エラー・スタックは、ttXlaError
自体およびttXlaErrorRestart
以外の関数をコールするたびに消去されます。
この関数の使用方法については、「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
を返します。
ノート: SQL_NO_DATA_FOUND は、sqlext.h (timesten.h に含まれています)に定義されています。 |
例
エラー・スタックに複数のエラーが存在する可能性があります。この例では、それらをすべて読み取る方法を示します。
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); } }
説明
表内のすべての列に関する情報を取得します。通常、返される列の数の出力パラメータ(nreturned
)は、colinfo
に返される列の数に設定されます。systemTableID
またはuserTableID
パラメータは、目的の表について記述します。このコールは、表の定義内の変更に対してシリアライズされます。
この関数の使用方法については、「列記述の取得」を参照してください。
構文
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 バッファに格納可能な列の最大数
この表に |
nreturned |
SQLINTEGER* |
返される列の数 |
例
この例では、次の定義を想定しています。
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」を参照してください。
パラメータ
パラメータ | 型 | 説明 |
---|---|---|
handle |
ttXlaHandle_h |
データベースのトランザクション・ログ・ハンドル |
LSN |
tt_XlaLsn_t* |
ハンドルの現行読取りログ・レコード識別子 |
ノート: tt_XlaLsn_t の、特にlogFile フィールドおよびlogOffset フィールドの使用方法が以前のリリースとは異なり、これらのフィールドが連続的に増加するLSNではなく、ログ・レコード識別子を参照する点に注意してください。「tt_XlaLsn_t」のノートを参照してください。 |
説明
表内の行に関する情報を取得します(ttXlaTblDesc_t
データ型に関する説明を参照)。userTableID
パラメータが0(ゼロ)以外の場合は、userTableIDの値を使用して目的の表を検出します。そうでない場合は、systemTableID
の値を使用して表を検出します。両方が0(ゼロ)の場合は、エラーが返されます。記述は、出力パラメータtblinfo
に格納されます。このコールは、表の定義内の変更に対してシリアライズされます。
構文
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* |
行の情報 |
例
この例では、次の定義を想定しています。
ttXlaTblDesc_t tabinfo; SQLUBIGINT systemTableID, userTableID;
システム識別子を使用して表の情報を取得するには、ttXlaTableByName
または他の方法を使用してシステム表識別子を検出して次のコールを実行します。
rc = ttXlaGetTableInfo(xlahandle, systemTableID, 0, &tabinfo);
また、表の情報は、ユーザー表識別子を使用して取得することもできます。
rc = ttXlaGetTableInfo(xlahandle, 0, userTableID, &tabinfo);
説明
この関数は、古いバージョンのXLA用に作成されたXLAアプリケーションを新しいバージョンで動作させるために、ttXlaSetVersion
と組み合せて使用します。通常、configured versionが古いバージョンで、actual versionが新しいバージョンです。
この関数は、現在構成されているXLAのバージョンを取得して、configuredVersion
パラメータに格納します。基礎となるXLAの実際のバージョンはactualVersion
に格納されます。ttXlaSetVersion
をコールしたため、コールごとにconfiguredVersion
の結果が異なる場合がありますが、actualVersion
の結果は同じままです。
構文
SQLRETURN ttXlaGetVersion(ttXlaHandle_h handle, out ttXlaVersion_t* configuredVersion, out ttXlaVersion_t* actualVersion)
パラメータ
パラメータ | 型 | 説明 |
---|---|---|
handle |
ttXlaHandle_h |
データベースのトランザクション・ログ・ハンドル |
configuredVersion |
ttXlaVersion_t* |
構成されているXLAのバージョン |
actualVersion |
ttXlaVersion_t* |
XLAの実際のバージョン |
説明
この関数は、トランザクション・ログから更新レコードの指定した最大数をフェッチし、コミットされたトランザクションに関連付けられているレコードを指定したバッファに返します。実際に返されたレコードの数が出力パラメータnreturned
に記録されます。この関数を使用するには、ブックマークがデータベース内に存在し、関数で使用する接続と関連付けられる必要があります。
ttXlaNextUpdate
をコールするたびに、最後に読み取られたレコードにブックマークが再設定され、次のレコードのリストを返すためにttXlaNextUpdate
への次のコールが有効にされます。
この関数の使用方法については、「トランザクション・ログからの更新レコードの取得」を参照してください。
構文
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(ゼロ)が返されます。 |
例
この例では、最大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]); }
説明
これは、ttXlaNextUpdate
関数と同様の処理を行いますが、使用可能なレコードがトランザクション・ログにない場合に待機する秒数を指定するパラメータseconds
があります。実際に待機する秒数は、seconds
に指定された値より最大で2秒長くなる場合があります。
「トランザクション・ログからの更新レコードの取得」も参照してください。
構文
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 |
ログが空の場合に待機する時間(秒) |
説明
TTXLA_NUMBER
値を、アプリケーションで使用可能なSQLBIGINT
値に変換します。
この関数は、TTXLA_NUMBER
型の列に対してのみコールします。データ型は、ttXlaGetColumnInfo
関数によって返されるttXlaColDesc_t
構造体から取得できます。
説明
TTXLA_NUMBER
値を、アプリケーションで使用可能な文字列に変換します。
この関数は、TTXLA_NUMBER
型の列に対してのみコールします。データ型は、ttXlaGetColumnInfo
関数によって返されるttXlaColDesc_t
構造体から取得できます。
構文
SQLRETURN ttXlaNumberToCString(ttXlaHandle_h handle, void* fromData, char* buf, int buflen int* reslen)
説明
TTXLA_NUMBER
値を、アプリケーションで使用可能な長い浮動小数点数値に変換します。
この関数は、TTXLA_NUMBER
型の列に対してのみコールします。データ型は、ttXlaGetColumnInfo
関数によって返されるttXlaColDesc_t
構造体から取得できます。
説明
TTXLA_NUMBER
値を、アプリケーションで使用可能なSQLINTEGER
値に変換します。
この関数は、TTXLA_NUMBER
型の列に対してのみコールします。データ型は、ttXlaGetColumnInfo
関数によって返されるttXlaColDesc_t
構造体から取得できます。
説明
TTXLA_NUMBER
値を、アプリケーションで使用可能なSQLSMALLINT
値に変換します。
この関数は、TTXLA_NUMBER
型の列に対してのみコールします。データ型は、ttXlaGetColumnInfo
関数によって返されるttXlaColDesc_t
構造体から取得できます。
説明
TTXLA_NUMBER
値を、アプリケーションで使用可能な小さい整数値に変換します。
この関数は、TTXLA_NUMBER
型の列に対してのみコールします。データ型は、ttXlaGetColumnInfo
関数によって返されるttXlaColDesc_t
構造体から取得できます。
説明
TTXLA_NUMBER
値を、アプリケーションで使用可能な符号なし整数値に変換します。
この関数は、TTXLA_NUMBER
型の列に対してのみコールします。データ型は、ttXlaGetColumnInfo
関数によって返されるttXlaColDesc_t
構造体から取得できます。
説明
TTXLA_DATE
値をODBCタイムスタンプに変換します。
この関数は、TTXLA_DATE
型の列に対してのみコールします。データ型は、ttXlaGetColumnInfo
関数によって返されるttXlaColDesc_t
構造体から取得できます。
説明
TTXLA_TIMESTAMP
値をODBCタイムスタンプに変換します。
この関数は、TTXLA_TIMESTAMP
型の列に対してのみコールします。データ型は、ttXlaGetColumnInfo
関数によって返されるttXlaColDesc_t
構造体から取得できます。
説明
データベースに対するトランザクション・ログ・ハンドルを初期化して、トランザクション・ログへのアクセスを有効にします。hdbc
パラメータは、データベースへのODBC接続ハンドルです。ODBC接続ごとに1つのXLAハンドルのみを作成します。ODBC接続に対してXLAハンドルを作成してから、ttXlaClose
でクローズするまで、ODBC接続に対して他のODBCコールは発行しないでください。
tag
は、XLAブックマークを識別する文字列です(「XLAブックマークについて」を参照)。tag
では、options
パラメータの指定に応じて、新しいブックマーク(レプリケートされていないブックマークまたはレプリケートされたブックマーク)、またはシステムに存在するブックマークを識別できます。handle
パラメータは、このコールによって初期化され、XLAに対する後続の各コールで指定する必要があります。
一部の処理は、ブックマークなしで実行できます。これらのタイプの処理を実行する場合は、XLANONE
オプションを使用して、ブックマークなしでトランザクション・ログにアクセスできます。次に、ブックマークなしでは実行できない処理を示します。
複数のアプリケーションが同時にトランザクション・ログから読取りを実行できます。この関数の使用方法については、「XLAの初期化およびXLAハンドルの取得」を参照してください。
この関数が成功すると、XLAは自動コミット・モードをOFFに設定します。
この関数が失敗しても、まだハンドルを作成する場合は、メモリー・リークを防ぐためにハンドルを閉じる必要があります。
構文
SQLRETURN ttXlaPersistOpen(SQLHDBC hdbc, SQLCHAR* tag, SQLUINTEGER options, out ttXlaHandle_h* handle)
パラメータ
パラメータ | 型 | 説明 |
---|---|---|
hdbc |
SQLHDBC |
データベースのODBCハンドル |
tag |
SQLCHAR* |
XLAブックマークの識別子
|
options |
SQLUINTEGER |
ブックマーク・オプションは、次のとおりです。
|
handle |
ttXlaHandle_h* |
このコールによって返されるトランザクション・ログ・ハンドル |
例
この例では、トランザクション・ログをオープンし、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);
説明
トランザクション・ログ・ハンドルで指定されたデータベースの現行読取りログ・レコード識別子を設定します。指定するLSN
の値が、ttXlaGetLSN
から返されるはずです。ユーザーが作成した値および現在のブックマークの初期読取りログ・レコード識別子より小さい値にはなりません。
この関数の使用方法については、「XLAブックマークについて」を参照してください。
パラメータ
パラメータ | 型 | 説明 |
---|---|---|
handle |
ttXlaHandle_h |
データベースのトランザクション・ログ・ハンドル |
LSN |
tt_XlaLsn_t* |
ハンドルの新しいログ・レコード識別子 |
ノート: tt_XlaLsn_t の、特にlogFile フィールドおよびlogOffset フィールドの使用方法が以前のリリースとは異なり、これらのフィールドが連続的に増加するLSNではなく、ログ・レコード識別子を参照する点に注意してください。「tt_XlaLsn_t」のノートを参照してください。 |
説明
表またはビューの所有者および名前を指定して、表またはマテリアライズド・ビューのシステム表識別子およびユーザー表識別子を検出します。この関数の使用方法については、「更新を監視する表の指定」を参照してください。
構文
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 |
説明
表の更新ステータスを返します。表は、ユーザー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」を参照してください。
この関数の使用方法については、「更新を監視する表の指定」を参照してください。
構文
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の古いステータス:
|
newstatus |
SQLINTEGER* |
XLAの新しいステータス:
|
例
次の例では、ttXlaTableByName
または他のなんらかの方法を使用して、システム表識別子またはユーザー表識別子が検出されていることを想定しています。
この例では、次の宣言を想定しています。
SQLUBIGINT systemTableID; SQLUBIGINT userTableID; SQLINTEGER currentStatus, requestedStatus;
システム表識別子を指定して表のステータスを検出するには、次のコールを実行します。
/* Get system table identifier into systemTableID, then ... */ rc = ttXlaTableStatus(xlahandle, systemTableID, 0, ¤tStatus, NULL);
currentStatus
の値は、表の更新追跡が有効になっている場合は0(ゼロ)以外になり、そうでない場合は0(ゼロ)になります。
システム表識別子を指定して表の更新追跡を有効にするには、次のように、リクエストするステータスを1に設定します。
requestedStatus = 1; rc = ttXlaTableStatus(xlahandle, systemTableID, 0, NULL, &requestedStatus);
次の例に示すように、新しい更新追跡ステータスを設定し、1回のコールで現在のステータスを取得できます。
requestedStatus = 1; rc = ttXlaTableStatus(xlahandle, systemTableID, 0, ¤tStatus, &requestedStatus);
前述のコールでは、システム表識別子による表の更新追跡が有効になり、以前の更新追跡ステータスが変数currentStatus
に取得されます。
これらのすべての例は、ユーザー表識別子を使用しても実行できます。ユーザー表識別子によって表の更新追跡ステータスを取得するには、次のコールを実行します。
/* Get system table identifier into userTableID, then ... */ rc = ttXlaTableStatus(xlahandle, 0, userTableID, ¤tStatus, NULL);
説明
キャッシュされた表定義が、処理中のXLAレコードと互換性があること確認します。列を追加または削除するためにALTER TABLE
を使用する場合のみ表定義が変更されます。
トランザクション・タイプADDCOLS
およびDRPCOLS
のXLAレコードのXLAストリームを監視すると、この関数の使用のオーバーヘッドを回避できます。トランザクション・タイプADDCOLS
またはDROPCOLS
の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* |
互換性情報を返します。
|
例
この例では、表の互換性を確認します。
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. */ }
説明
TTXLA_TIME
値を、アプリケーションで使用可能なODBC C値に変換します。この関数の使用方法については、「複合データ型の変換」を参照してください。
この関数は、TTXLA_TIME
型の列に対してのみコールします。データ型は、ttXlaGetColumnInfo
関数によって返されるttXlaColDesc_t
構造体から取得できます。
パラメータ
パラメータ | 型 | 説明 |
---|---|---|
fromData |
void* |
トランザクション・ログから返されたTIME値へのポインタ |
returnData |
TIME_STRUCT* |
変換された時間を保持するように割り当てられた記憶域へのポインタ |
例
この例では、トランザクション・ログ・レコードに返された行からTIME値pColVal
を取得するために、ttXlaColDesc_t
構造体に返されたoffset
値を使用していると想定しています。
TIME_STRUCT time; rc = ttXlaTimeToODBCCType(pColVal, &time);
説明
TTXLA_TIMSTAMP_TT
値を、アプリケーションで使用可能なODBC C値に変換します。この関数の使用方法については、「複合データ型の変換」を参照してください。
この関数は、TTXLA_TIMSTAMP_TT
型の列に対してのみコールします。データ型は、ttXlaGetColumnInfo
関数によって返されるttXlaColDesc_t
構造体から取得できます。
パラメータ
パラメータ | 型 | 説明 |
---|---|---|
fromData |
void* |
トランザクション・ログから返されたTIMESTAMP値へのポインタ |
returnData |
TIMESTAMP_STRUCT* |
変換されたタイムスタンプを保持するように割り当てられた記憶域へのポインタ |
例
この例では、トランザクション・ログ・レコードに返された行からTIMESTAMP値pColVal
を取得するために、ttXlaColDesc_t
構造体に返されたoffset
値を使用していると想定しています。
TIMESTAMP_STRUCT timestamp; rc = ttXlaTimeStampToODBCCType(pColVal, ×tamp);
構文
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 |
表に含めることができる列の最大数
ノート: この表に |
nreturned |
SQLINTEGER* |
返される列の数 |
構文
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* |
比較結果を返します。
|
例
XLAのconfigured
バージョンとactual
バージョンを比較するには、次のコールを実行します。
ttXlaVersion_t configured, actual; SQLINTEGER comparision; rc = ttXlaGetVersion (xlahandle, &configured, &actual); rc = ttXlaVersionCompare (xlahandle, &configured, &actual, &comparison);
ノート
XLAベースのレプリケーションで2つのシステムを接続する場合は、次の手順を実行します。
プライマリ・サイトで、ttXlaGetVersion
を使用してXLAバージョンを取得します。このバージョン情報をスタンバイ・サイトに送信します。
スタンバイ・サイトで、ttXlaGetVersion
を使用してXLAバージョンを取得します。ttXlaVersionCompare
を使用して古いバージョンを判別します。2つのサイト間で適切な処理を行うには、古いバージョン番号を使用する必要があります。ttXlaSetVersion
を使用してスタンバイ・サイトで使用するインタフェースのバージョンを指定します。古いバージョン番号をプライマリ・サイトに返信します。
選択したバージョンがプライマリ・サイトで受信された後、ttXlaSetVersion
を使用して、使用するXLAのバージョンを指定します。
構文
SQLRETURN ttXlaVersionTableInfo(ttXlaHandle_h handle, ttXlaUpdateDesc_t* record, out ttXlaTblVerDesc_t* tblinfo)
パラメータ
パラメータ | 型 | 説明 |
---|---|---|
handle |
ttXlaHandle_h |
データベースのトランザクション・ログ・ハンドル |
record |
ttXlaUpdateDesc_t* |
処理されるXLAレコード |
tableinfo |
ttXlaTblVerDesc_t* |
表定義に関する情報 |
『Oracle TimesTen In-Memory Database開発者および管理者ガイド』に記載されているとおり、TimesTenのレプリケーションは、ほとんどの顧客要件を満たすには十分ですが、XLA関数を使用して、1つのデータベースから別のデータベースに更新をレプリケートすることもできます。この方法で独自のレプリケーション・スキームをXLAの上に実装することはかなり困難ですが、TimesTenのレプリケーションがなんらかの理由で実行できない場合には検討できます。
この項では、レプリケーション・メカニズムとしてXLAのみを使用する関数について説明します。関数は、アルファベット順に示されています。
この関数はXLAレプリケーション機能の一部であり、一般的なXLAアプリケーションでの使用には適していません。
説明
トランザクション・ログ・ハンドルに関連付けられているデータベースに更新を適用します。戻り値は、更新が成功したかどうかを示します。また、更新によって永続的な問題が発生したかどうかも示します。(更新で一時的な問題(デッドロック、タイムアウトなど)が発生したかどうかを確認するには、ttXlaError
をコールし、エラー・コードを確認する必要があります。)
ttXlaUpdateDesc_t
レコードがトランザクション・コミットの場合、基盤となるデータベース・トランザクションがコミットされます。ttXlaApply
で他のトランザクション・コミットは実行されません。パラメータtest
がtrueの場合は、レコードの更新および削除のために、更新記述内の古い値がデータベースの現在の内容と比較されます。更新記述内の古い値がデータベースの対応する行と一致しない場合、この関数は更新を拒否して、sb_ErrXlaTupleMismatch
エラーを返します。
この関数の使用方法については、「レプリケーション・メカニズムとしてのXLAの使用」を参照してください。
ノート: 表定義が最初にトランザクション・ログに書き込まれてから変更された場合、ttXlaApply は使用できません。文のレベルではなく、行のレベルで一意キー制約および外部キー制約がチェックされます。 |
必要な権限
ADMIN
ttXlaApply
処理の対象となるターゲット・データベースでは、他の権限が必要になる場合があります。たとえば、ターゲット・データベースにCREATETAB
(表の作成)レコードを適用するには、必要に応じて、CREATE TABLE
またはCREATE ANY TABLE
権限を持つ必要があります。
パラメータ
パラメータ | 型 | 説明 |
---|---|---|
handle |
ttXlaHandle_h |
データベースのトランザクション・ログ・ハンドル |
record |
ttXlaUpdateDesc_t* |
SQL文を生成するトランザクション |
テスト |
SQLINTEGER |
古い値のテスト:
|
結果
コールが成功した場合は、SQL_SUCCESS
が返されます。返されない場合は、ttXlaError
を使用してエラーをレポートします。
test
が1で、ttXlaApply
で更新の競合が検出されると、sb_ErrXlaTupleMismatch
エラーが返されます。
例
この例では、既存のレコードの以前の値をテストせずに、更新をデータベースに適用します。
ttXlaUpdateDesc_t record; rc = ttXlaApply(xlahandle, &record, 0);
この関数はXLAレプリケーション機能の一部であり、一般的なXLAアプリケーションでの使用には適していません。
説明
トランザクション・ログ・ハンドルに対して適用中の現行のトランザクションをコミットします。トランザクションが完了しているかどうかに関係なく、このルーチンはトランザクションをコミットします。このルーチンをコールすると、ttXlaApply
によってレポートされた一時的なエラー(タイムアウトまたはデッドロック)に応答でき、ttXlaApplyは、エラーが発生しなければ現在のトランザクションを適用します。
この関数の使用方法については、「タイムアウトおよびデッドロックのエラーの処理」を参照してください。
この関数はXLAレプリケーション機能の一部であり、一般的なXLAアプリケーションでの使用には適していません。
ノート: この関数は、現在はLOBロケータでは動作しません。 |
説明
更新レコードの結果を示すSQL DMLまたはDDL文を生成します。生成された文は、データベースには適用されません。かわりに、文は、最大サイズがmaxLen
パラメータによって指定される特定のバッファに返されます。バッファの実際のサイズはactualLen
によって返されます。更新および削除のレコードの場合、正しいSQLを生成するために、ttXlaGenerateSQL
には、NULL値可能でない列に対する主キー索引または一意索引が必要です。
生成されたSQL文は、XLAハンドルのODBC接続に関係付けられている接続文字セットでエンコードされます。
「TimesTen以外のデータベースへの更新のレプリケート」も参照してください。
構文
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* |
バッファの実際の長さ(バイト) |
この関数はXLAレプリケーション機能の一部であり、一般的なXLAアプリケーションでの使用には適していません。
説明
この関数は、keys
パラメータに指定されているキー値を持つ特定の表のレコードを検索します。keys
およびresult
レコードの書式は、通常の行の書式と同じです。この関数では、基礎となる表に主キーが必要です。
構文
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* |
レコードの実際のサイズ |
この関数はXLAレプリケーション機能の一部であり、一般的なXLAアプリケーションでの使用には適していません。
説明
トランザクション・ログ・ハンドルに対して適用中の現行のトランザクションをロールバックします。このルーチンをコールすると、ttXlaApply
によってレポートされた一時的なエラー(タイムアウトまたはデッドロック)に応答できます。
この関数の使用方法については、「タイムアウトおよびデッドロックのエラーの処理」を参照してください。
この関数はXLAレプリケーション機能の一部であり、一般的なXLAアプリケーションでの使用には適していません。
説明
レプリケーション・メカニズムとしてXLAを使用する場合、この関数は、マスター・データベースから受信したttXlaTblDesc_t
構造体内の名前付き表が、トランザクション・ログ・ハンドルに関連付けられているサブスクライバ・データベースまたはデータベースと互換性があることを検証します。compat
パラメータは、表に互換性があるかどうかを示します。
この関数の使用方法については、「データベース間での表の互換性の確認」を参照してください。
構文
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* |
互換性情報を返します。
|
例
この例では、表の互換性を確認します。
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 */ }
この項では、この章で説明されているXLA関数で使用されるCデータ構造体について説明します。これらの構造体は、次のファイルで定義されています。
installation_dir
/include/tt_xla.h
XLAアプリケーションの作成時に、このファイルをインクルードする必要があります。
表9-1 Cデータ構造体の概要
Cデータ構造体 | 説明 |
---|---|
|
レコード・タイプについて記述します。XLAによって返されるレコードの先頭で使用されます。 |
|
更新レコードについて記述します。 |
|
|
|
|
|
|
|
|
|
ブックマークで使用されるログ・レコード識別子について記述します。この構造体は、 |
|
XLAブックマークで使用されるログ・レコード識別子について記述します。 |
ほとんどCデータ構造体は、データのレコード・タイプおよび長さについて記述する標準ヘッダーで始まります。標準ヘッダーの型はttXlaNodeHdr_t
です。
このヘッダーには、次のフィールドがあります。
フィールド | 型 | 説明 |
---|---|---|
nodeType |
char |
レコードのタイプ。
|
byteOrder |
char |
レコードのバイト順序。
|
length |
SQLUINTEGER |
すべての添付ファイルを含むレコードの全長 |
この構造体は、データベース内の単一行(またはタプル)への更新処理について記述します。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 |
レコード・タイプ。
|
フラグ |
SQLUSMALLINT |
レコード更新での特別なオプション。
特定の列の値が0(ゼロ)の場合は、その列にデフォルト値がないことを示します。0(ゼロ)以外のすべての値のデフォルト値は文字列内で連結され、デフォルト値の長さを示す配列値の順序で示されます。たとえば、デフォルト値が これらの各 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
処理の場合、特別な行の値は、新しい表について記述するttXlaTblDesc_t
レコードおよびその後に続く、各列について記述するttXlaColDesc_t
レコードで構成されています。
ALTER TABLE
処理の場合、特別な行の値は、ttXlaDropTableTup_t
またはttXlaAddColumnTup_t
値およびその後に続く、列について記述するttXlaColDesc_t
レコードで構成されます。
DROP TABLE
処理の場合、行の値は次のようになります。
フィールド | 型 | 説明 |
---|---|---|
tblName |
char(31) |
削除される表の名前 |
tblOwner |
char(31) |
削除される表の所有者 |
TRUNCATE TABLE
処理の場合、行の値は次のようになります。
フィールド | 型 | 説明 |
---|---|---|
tblName |
char(31) |
切り捨てられる表の名前。 |
tblOwner |
char(31) |
切り捨てられる表の所有者 |
CREATE INDEX
処理の場合、行の値は次のようになります。
フィールド | 型 | 説明 |
---|---|---|
tblName |
char(31) |
索引が定義されている表の名前。 |
tblOwner |
char(31) |
索引が定義される表の所有者 |
ixName |
char(31) |
新しい索引の名前 |
フラグ |
char(31) |
索引フラグ。
|
nixcols |
SQLUINTEGER |
索引付けされる列の数 |
ixColsSys |
SQLUINTEGER(16) |
システム番号を使用して索引付けされる列番号 |
ixColsUser |
SQLUINTEGER(16) |
ユーザー定義の列IDを使用して索引付けされる列番号 |
ixType |
char |
索引のタイプ。
|
ixUnique |
char |
索引の一意性。
|
ページ |
SQLUINTEGER |
ハッシュ索引のページ数 |
DROP INDEX
処理の場合、行の値は次のようになります。
フィールド | 型 | 説明 |
---|---|---|
tblName |
char(31) |
索引が削除された表の名前 |
tblOwner |
char(31) |
索引が削除された表の所有者 |
ixName |
char(31) |
削除された索引の名前 |
ADD COLUMN
処理の場合、行の値は次のようになります。
フィールド | 型 | 説明 |
---|---|---|
ncols |
SQLUINTEGER |
追加列の数 |
この特別な行の後に、新しい列について記述するttXlaColDesc_t
レコードが続きます。
DROP COLUMN
処理の場合、行の値は次のようになります。
フィールド | 型 | 説明 |
---|---|---|
ncols |
SQLUINTEGER |
削除された列の数 |
この特別な行の後に、削除された列について記述するttXlaColDesc_t
レコードの配列が続きます。
CREATE SEQUENCE
処理の場合、行の値は次のようになります。
フィールド | 型 | 説明 |
---|---|---|
sqName |
char(31) |
順序の名前 |
sqOwner |
char(31) |
順序の所有者 |
cycle |
char |
サイクル・フラグ
順序番号ジェネレータが、最大値または最小値に達した後も番号の生成を続行するかどうかを指定します。
|
minval |
SQLBIGINT |
順序の最小値 |
maxval |
SQLBIGINT |
順序の最大値 |
incr |
SQLBIGINT |
順序番号間の増分
正の値は昇順、負の値は降順を示します。降順の場合、値の範囲は |
DROP SEQUENCE
処理の場合、行の値は次のようになります。
フィールド | 型 | 説明 |
---|---|---|
sqName |
char(31) |
順序の名前 |
sqOwner |
char(31) |
順序の所有者 |
CREATE VIEW
処理の場合、行の値は次のようになります。
ノート: これは、マテリアライズド・ビューおよび非マテリアライズド・ビューのどちらにも適用されます。 |
フィールド | 型 | 説明 |
---|---|---|
vwName |
char(31) |
ビューの名前 |
vwOwner |
char(31) |
ビューの所有者 |
sysTableID |
SQLUBIGINT |
SYS.TABLES に格納されたシステム表ID |
DROP VIEW
処理の場合、行の値は次のようになります。
ノート: これは、マテリアライズド・ビューおよび非マテリアライズド・ビューのどちらにも適用されます。 |
フィールド | 型 | 説明 |
---|---|---|
vwName |
char(31) |
ビューの名前 |
vwOwner |
char(31) |
ビューの所有者 |
CREATE SYNONYM
処理の場合、行の値は次のようになります。
フィールド | 型 | 説明 |
---|---|---|
synName |
char(31) |
シノニムの名前 |
synOwner |
char(31) |
シノニムの所有者 |
objName |
char(31) |
シノニムが指すオブジェクトの名前 |
objOwner |
char(31) |
シノニムが指すオブジェクトの所有者 |
isPublic |
char |
シノニムがパブリックかどうかを示します。
|
isReplace |
char |
シノニムがCREATE OR REPLACE を使用して作成されたかどうかを示します。
|
DROP SYNONYM
処理の場合、行の値は次のようになります。
フィールド | 型 | 説明 |
---|---|---|
synName |
char(31) |
シノニムの名前 |
synOwner |
char(31) |
シノニムの所有者 |
isPublic |
char |
シノニムがパブリックかどうかを示します。
|
SET TABLE ID
処理の場合、更新レコードの主要部分で以前に割り当てられたアプリケーション表識別子を使用し、アプリケーション表識別子の新しい値を次の特別な行に指定するように記述されます。
フィールド | 型 | 説明 |
---|---|---|
newID |
SQLUBIGINT |
新しいユーザー定義の表ID |
更新レコードを取得する手順および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」を参照してください。
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
構造体を使用して表現されます。この構造体は、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
配列には、対応するアプリケーション指定の列識別子が含まれます。
このデータ構造体には、表のバージョン番号とttXlaTblDesc_t
が含まれています。この構造体はttXlaVersionTableInfo
によって返されます。この構造体には、次のフィールドがあります。
フィールド | 型 | 説明 |
---|---|---|
tblDesc |
ttXlaTblDesc_t |
表記述 |
tblVer |
SQLBIGINT |
システム生成表のバージョン番号 |
列情報は、ttXlaGetColumnInfo
関数によって返される、この構造体を使用して提供されます。
この構造体には、次のフィールドがあります。
フィールド | 型 | 説明 |
---|---|---|
header |
ttXlaNodeHdr_t |
標準データ・ヘッダー |
colName [tt_NameLenMax] |
char |
列の名前 |
pad0 |
SQLUINTEGER |
4バイト境界まで埋込み |
sysColNum |
SQLUINTEGER |
表の作成時またはその後の変更時に決定された列の序数
|
userColNum |
SQLUINTEGER |
列の序数(オプションでユーザーが指定した場合)
これは、0(ゼロ)または |
dataType |
SQLUINTEGER |
ODBC TTXLA_* コードの構造体
「XLAデータ型について」を参照してください。 |
size |
SQLUINTEGER |
列の最大または基本サイズ |
offset |
SQLUINTEGER |
列の固定長部分に対するオフセット |
nullOffset |
SQLUINTEGER |
NULLバイトに対するオフセット、またはNULL値可能でない場合は0(ゼロ) |
precision |
SQLSMALLINT |
DECIMAL型の数値の精度 |
scale |
SQLSMALLINT |
DECIMAL型の数値のスケール |
フラグ |
SQLUINTEGER |
列フラグ。
|
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バイトのオフセット値を指すアドレスです。オフセット・アドレスをオフセット値に追加すると、行の可変長部分の列データのアドレスを取得できます。この位置にある最初の8バイトはデータの長さで、その後に実際のデータが続きます。可変長データの場合、返されるsize値は列の許容最大サイズです。次の例9-1を参照してください。
NULL値が含まれる可能性がある列の場合、nullOffset
はレコードのNULLバイトを指します。この値は、列がNULLの場合は1、NULLでない場合は0(ゼロ)になります。詳細は、「NULL値の検出」を参照してください。
flags
ビットは、列がNULL値可能であるかどうか、主キーの一部となるかどうか、またはアウトラインで格納されるかどうかを定義します。
sysColNum
値は、列に割り当てるシステム列番号です。この値は、最初の列に対しては1から始まります。
XLAでのLOBのサポートは、次のように制限されています。
|
例9-1 VARCHAR2文字列のコピーと出力
固定長列データの場合、列のアドレスは、次のようにttXlaColDesc_t構造体の
offset値に行のアドレスを追加したものです。
ttXlaColDesc_t colDesc; void* pColVal = colDesc->offset + row;
列の値は、データ型に対応する型ポインタを使用してこのポインタを参照解除すると取得できます。たとえば、SQL_INTEGER
の場合、ODBC型はSQLINTEGER
であるため、列の値は次のように入力すると取得できます。
*((SQLINTEGER*) pColVal))
可変長列データの場合、前述の手順で計算されたpColVal
は4バイトのオフセット値のアドレスになります。このオフセット値をpColVal
のアドレスに追加すると、可変長列データの先頭を指すポインタが示されます。この位置にある最初の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);
ブックマークで使用されるログ・レコード識別子の記述です。この構造体は、ttXlaUpdateDesc_t
構造体によって使用されます。
フィールド | 型 | 説明 |
---|---|---|
logFile |
SQLUBIGINT |
ログ・レコード識別子の上位部分 |
logOffset |
SQLUBIGINT |
ログ・レコード識別子の下位部分 |
ノート: logFile フィールド名およびlogOffset フィールド名は、下位互換性を保つために保持されていますが、使用方法は変更されています。以前のリリースでは、値は連続的に増加するLSNを参照しており、この値は具体的な意味を持ち、ログ・ファイル番号とバイト・オフセットを表していました。現在ではログ・レコード識別子を参照していて、この識別子は、より抽象的で、ログ・ファイル番号やバイト・オフセットとは直接関係しません。ログ・レコード識別子の順序に関して想定できることは、ログ・レコード識別子Aよりも後に読み取られたログ・レコード識別子Bは、より大きい値を持つということのみです。 |
ブックマークで使用されるログ・レコード識別子の記述です。この構造体はttXlaGetLSN
関数によって返され、ttXlaSetLSN
関数によって使用されます。
checksum
はXLAハンドル固有であり、すべてのログ・レコード識別子が特定のXLA接続と関連付けられていることを保証します。
フィールド | 型 | 説明 |
---|---|---|
checksum |
SQLUINTEGER |
有効なログ・レコード識別子ハンドルであることを保証するためのチェックサム |
xid |
SQLUSMALLINT |
トランザクションID |
logFile |
SQLUBIGINT |
ログ・レコード識別子の上位部分 |
logOffset |
SQLUBIGINT |
ログ・レコード識別子の下位部分 |
ノート: logFile フィールド名およびlogOffset フィールド名は、下位互換性を保つために保持されていますが、使用方法は変更されています。以前のリリースでは、値は連続的に増加するLSNを参照しており、この値は具体的な意味を持ち、ログ・ファイル番号とバイト・オフセットを表していました。現在ではログ・レコード識別子を参照していて、この識別子は、より抽象的で、ログ・ファイル番号やバイト・オフセットとは直接関係しません。ログ・レコード識別子の順序に関して想定できることは、ログ・レコード識別子Aよりも後に読み取られたログ・レコード識別子Bは、より大きい値を持つということのみです。 |