| Oracle® TimesTen In-Memory Database TTClassesガイド 11gリリース2 (11.2.2) B66724-05 |
|
 前 |
 次 |
このリファレンスの章では、TTClassesの外部クラスおよびそのメソッドについて説明します。内容は次のとおりです。
|
注意: この章で説明するメソッドのほとんどでは、コール・シーケンスの終わりにTTStatus&パラメータを含むシグネチャもサポートされています。これは、メソッド・コールの例外を抑制し、かわりにエラーに関して手動でTTStatusオブジェクトを処理する状況に対応するためです。ただし、このモードの使用は推奨されないため、このシグネチャについての説明は特に記載されていません。詳細および例については、「TTStatus」の「使用方法」に関する項を参照してください。 |
この項では、次のクラスについて説明します。
TTGlobalクラスは、TTClassesのロギング機能を提供します。
TTGlobalロギング機能は、TTClassesプログラム内で発生する問題のデバッグに非常に役立つことがあります。ただし、冗長度の高いロギング・レベル(TTLog::TTLOG_INFOおよびTTLog::TTLOG_DEBUG)の場合は、膨大な出力が生成される可能性があることに注意してください。これらのロギング・レベルは、開発時または不具合の診断時に使用してください。これらは、多くの本番環境には適していません。
マルチスレッド・プログラムからロギングを行う際、ディスクへの書込み時に、プログラムの別スレッドからのログ出力が入り混じる問題が発生する場合があります。この問題を軽減するには、次の例のように、ios_base::unitbuf I/Oストリーム・マニピュレータを使用してostreamバッファリングを無効にし、TTClassesのロギングがロギング・レベルTTLog::TTLOG_ERRでapp_log.txtファイルに送信されるようにします。
ofstream log_file("app_log.txt");
log_file << std::ios_base::unitbuf;
TTGlobal::setLogStream(log_file);
TTGlobal::setLogLevel(TTLog::TTLOG_ERR);
TTGlobalの使用方法の詳細は、「TTClassesロギングの使用」を参照してください。
| メソッド | 説明 |
|---|---|
disableLogging() |
TTClassesのロギングを無効にします。 |
setLogLevel() |
TTClassesロギングの冗長レベルを指定します。 |
setLogStream() |
TTClassesのロギング情報の送信先を指定します。 |
sqlhenv() |
基礎となるODBC環境オブジェクト(SQLHENV型)を返します。 |
static void disableLogging()
このメソッドは、すべてのTTClassesロギングを無効にします。次の2つの文は同一であることに注意してください。
TTGlobal::disableLogging(); TTGlobal::setLogLevel(TTLog::TTLOG_NIL);
static void setLogLevel(TTLog::TTLOG_LEVEL level)
このメソッドは、TTClassesロギングの冗長レベルを指定します。表3-1に、TTClassesのロギング・レベルを示します。これらのレベルは累積されます。
表3-1 TTClassesのロギング・レベル
| ロギング・レベル | 説明 |
|---|---|
|
|
ロギングは実行されません。 |
|
|
致命的エラー(TTClassesメソッドの重大な誤用)が記録されます。 |
|
|
すべてのエラー( |
|
|
(デフォルト)警告と |
|
|
情報メッセージ( |
|
|
デバッグ用の追加情報( |
たとえば、ロギング・レベルをTTLog::TTLOG_ERRに設定するには、次の行をプログラムに追加します。
TTGlobal::setLogLevel(TTLog::TTLOG_ERR);
static void setLogStream(ostream& stream)
TTClassesのロギング情報の送信先を指定します。デフォルトでは、TTClassesロギングが有効な場合、stderrにロギングします。このメソッドを使用すると、ロギングをapp_log.txtに設定する次の例のように、ユーザー・アプリケーションはロギングをファイル(または他の任意のostream&)に指定できます。
ofstream log_file("app_log.txt");
TTGlobal::setLogStream(log_file);
TTStatusクラスは、TTClassesライブラリ内の他のクラスで、エラーおよび警告の例外を捕捉するために使用されます。TTStatusは、ODBC関数SQLErrorの付加価値C++ラッパーと考えることができます。
TTClassesのエラー処理方法として推奨されるモードは、エラーまたは警告が発生した場合に必ずTTStatusオブジェクトが例外としてスローされることです。これを行うには、TTClassesライブラリとアプリケーションを、TTEXCEPTプリプロセッサ変数を有効にしてコンパイルする必要があります。(TTClassesはデフォルトでこの方法でコンパイルされます。)これによって、C++アプリケーションで{try/catch}ブロックによる障害の検出とリカバリが可能となります。
例3-1にTTStatusの標準的な使用方法を示します。例3-3も参照してください。
例3-1 例外処理
...
TTCmd myCmd;
try {
myCmd.ExecuteImmediate(&conn, "create table dummy (c1 int)");
}
catch (TTStatus st) {
cerr << "Error creating table: " << st << endl;
// Rollback, exit(), throw -- whatever is appropriate
}
TTStatusでの使用がサポートされる別のモードでは(ただし一般的ではない)、TTEXCEPTが有効な場合に、例外を選択的に抑制し、アプリケーションがTTStatusオブジェクトのエラー状態の有無を手動で確認できるようになります。このモードは、特定のメソッド・コールに対して使用可能で、それには、値TTStatus::DO_NOT_THROWでTTStatusオブジェクトを初期化し、そのオブジェクトをメソッド・コールの最後のパラメータとして渡します。この章で説明するTTClassesのメソッドのほとんどで、コール・シーケンスの最後のパラメータとして、このTTStatus&パラメータを含むシグネチャもサポートされています。
次の例3-2に、この使用方法を示します。
例3-2 例外の抑制
...
TTCmd myCmd;
TTStatus myStat(TTStatus::DO_NOT_THROW);
myCmd.ExecuteImmediate(&conn, "create table dummy (c1 int)", myStat);
if (myStat.rc == SQL_ERROR)
{
// handle the error
}
...
別の操作モードでは(推奨されていません)、TTClassesとアプリケーションをTTEXCEPTフラグを無効にしてコンパイルします。この場合、例外はスローされず、エラーを処理するにはメソッド・コール内のTTStatus&パラメータを使用する方法しかありません。この方法でコンパイルすると、より新しいメソッド・シグネチャは(TTStatus&パラメータなし)は利用できなくなります。
TTStatusには、次のサブクラスがあります。
TTWarningはTTStatusのサブクラスであり、ODBC警告(リターン・コードSQL_SUCCESS_WITH_INFO)をカプセル化するために使用されます。
ODBC警告(たとえば、RETURN RECEIPT警告)は、通常ODBCエラーほど重大ではないので、一般的は別のロジックを使用して処理する必要があります。ODBCエラーは、プログラムを記述して処理する必要があります。プログラムによるODBC警告の処理が保証される場合もありますが、通常は単純にログに記録するだけで十分です。
例3-3に、TTErrorサブクラスとTTWarningサブクラスの使用方法を示します。
例3-3 例外処理時のエラーと警告の区別
この例では、TTErrorとTTWarningの使用方法を示します。ODBCエラーでは、TTErrorオブジェクトがスローされます。ODBC警告では、TTWarningオブジェクトがスローされます。
// catching TTError & TTWarning exceptions
try {
// some TTClasses method calls
}
catch (TTWarning warn) {
cerr << "Warning encountered: " << warn << endl;
}
catch (TTError err) {
// handle the error; this could be a serious problem
}
| メンバー | 説明 |
|---|---|
rc |
失敗したODBCコールからのリターン・コード(SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_ERROR、SQL_NO_DATA_FOUNDまたはSQL_INVALID_HANDLE)です |
native_error |
ODBCコールに失敗した場合のTimesTenネイティブ・エラー番号(存在する場合)です |
odbc_error |
ODBCコールに失敗した場合のODBCエラー状態です |
err_msg |
ODBCコールに失敗した場合のASCII形式の出力可能なエラー・メッセージです |
TTSTATUS_ENUM |
エラー・ステータスおよびエラー処理の列挙です
|
| メソッド | 説明 |
|---|---|
isConnectionInvalid() |
データベース接続が無効であるかどうかを示します。 |
ostream() |
エラーをストリームに出力します。 |
throwError() |
TTStatusオブジェクトからエラーをスローします(一般的には使用しません)。 |
bool isConnectionInvalid() const
データベース接続が無効の場合はTRUEを返し、有効の場合はFALSEを返します。無効とは、具体的にはTimesTenエラー846または994が発生したときのことを意味します。それらのエラーの詳細は、『Oracle TimesTen In-Memory Databaseエラー・メッセージおよびSNMPトラップ』のエラー0から999に関する説明を参照してください。
void throwError()
これは標準的ではない、例外をスローする代替の方法です。多くの場合、次の2つのコードのブロックは同等ですが、前者の方がより標準的です。
try {
// ...
if (/* something has gone wrong */)
throw stat;
}
catch (TTStatus st) {
cerr << "Caught exception: " << st << endl;
}
または
try {
// ...
if (/* something has gone wrong */)
stat.throwError();
}
catch (TTStatus st) {
cerr << "Caught exception: " << st << endl;
}
TTConnectionクラスは、データベースに対する接続という概念をカプセル化します。TTConnectionは、ODBC接続ハンドル(SQLHDBC)の付加価値C++ラッパーと考えることができます。
TimesTenを使用するすべてのアプリケーションは、1つ以上のTTConnectionオブジェクトを作成する必要があります。
同時に複数のスレッドからTimesTenを使用するマルチスレッド・アプリケーションでは、TTConnectionオブジェクトを複数作成する必要があります。次のいずれかの方法を使用します。
スレッドの作成時に、各スレッドに1つのTTConnectionオブジェクトを作成します。
アプリケーション・プロセスの開始時に、TTConnectionオブジェクトのプールを作成します。それらはプロセス内の複数のスレッドで共有されます。このオプションの詳細は、「TTConnectionPool」を参照してください。
TimesTen接続は、親プロセスから継承できません。プロセスが、子プロセスを作成する(分岐)前にデータベース接続を開いた場合、子が同じ接続を使用することはできません。子が親のデータベース接続を使用しようとすると、アプリケーションが失敗したりコア・ダンプが発生する場合があります。
接続および切断は、比較的負荷の高い操作であるため、アプリケーションでは頻繁にデータベース接続を行ったり、切断しないようにする必要があります。また、短期間の接続では準備済文のメリットがなくなります。そのかわりに、アプリケーション・プロセスの開始時にデータベース接続を確立し、そのプロセスの存続中はそれを再利用します。
「TTCmd、TTConnectionおよびTTConnectionPoolの使用」も参照してください。
|
注意: 基礎となるODBC接続オブジェクトを直接操作する必要がある場合は、TTConnection::getHdbc()メソッドを使用します。 |
データベースに接続する権限は、CREATE SESSION権限を使用して、直接またはPUBLICロールを介してユーザーに付与する必要があります。「接続のアクセス制御」を参照してください。
| メンバー | 説明 |
|---|---|
DRIVER_COMPLETION_ENUM |
接続先データベースの指定を求めるプロンプトを表示するかどうかを指定します(これは、接続文字列でデータベースが指定されているかどうかにも左右されます)。
有効な値は、 |
| メソッド | 説明 |
|---|---|
Commit() |
データベースにトランザクションをコミットします。 |
Connect() |
新しいデータベース接続を開きます。 |
Disconnect() |
データベース接続を閉じます。 |
DurableCommit() |
データベースに対する永続コミット操作を実行します。 |
getHdbc() |
この接続と関連付けられているODBC接続ハンドル(型SQLHDBC)を返します。 |
GetTTContext() |
接続のコンテキスト値を返します。 |
isConnected() |
オブジェクトがTimesTenに接続されている場合はTRUEを返します。 |
Rollback() |
最後のCommit()またはRollback()へのコールの後に、この接続を介して行われたデータベースの変更をロールバックします。 |
SetAutoCommitOff() |
接続の自動コミットを無効にします。 |
SetAutoCommitOn() |
接続の自動コミットを有効にします。 |
SetIsoReadCommitted() |
接続のトランザクション分離レベルをTXN_READ_COMMITTEDに設定します。 |
SetIsoSerializable() |
接続のトランザクション分離レベルをTXN_SERIALIZABLEに設定します。 |
SetLockWait() |
TimesTen組込みプロシージャttLockWaitをコールして、接続のロック・タイムアウト間隔を設定します。 |
SetPrefetchCloseOff() |
TT_PREFETCH_CLOSE接続オプションを無効にします。 |
SetPrefetchCloseOn() |
TT_PREFETCH_CLOSE接続オプションを有効にします。これは、TimesTenへのクライアント/サーバー接続でのSELECT問合せのパフォーマンスを最適化する場合に有効です。 |
SetPrefetchCount() |
TimesTen ODBCドライバSQLFetchコールがSELECT文をプリフェッチする行数をユーザー・アプリケーションによって調整できます。 |
void Commit()
データベースにトランザクションをコミットします。これにより、Commit()またはRollback()メソッドへの最後のコール後に、接続で実行されたすべての操作がコミットされます。エラーが発生するとTTStatusオブジェクトが例外としてスローされます。「Rollback()」も参照してください。
virtual void Connect(const char* connStr) virtual void Connect(const char* connStr, const char* username, const char* password) virtual void Connect(const char* connStr, DRIVER_COMPLETION_ENUM driverCompletion)
新しいデータベース接続を開きます。connStrパラメータで指定された接続文字列を使用して接続が作成されます。ユーザーとパスワードを、接続文字列の一部、別のパラメータまたはDRIVER_COMPLETION_ENUM値として(「Publicメンバー」を参照)指定します。後述のメソッドDisconnect()も参照してください。
データベースに接続する権限は、CREATE SESSION権限を使用して、直接またはPUBLICロールを介してユーザーに付与する必要があります。「接続のアクセス制御」を参照してください。
例3-4 Connect()メソッドの使用およびエラーの確認
エラーが発生するとTTStatusオブジェクトが例外としてスローされます。すべての例外の警告は通常は情報を示すもので、通常は無視しても問題ありません。Connect()メソッドを使用する場合は、次のロジックの使用が推奨されます。
TTWarningとTTErrorは、TTStatusのサブクラスです。
TTConnection conn;
...
try {
conn.Connect("DSN=mydsn", "myuser", "mypassword");
}
catch (TTWarning warn) {
// warnings from Connect() are usually informational
cerr << ''Warning while connecting to TimesTen: '' << warn << endl;
}
catch (TTError err) {
// handle the error; this could be a serious problem
}
void Disconnect()
データベース接続を閉じます。エラーが発生するとTTStatusオブジェクトが例外としてスローされます。前述のメソッドConnect()も参照してください。
void DurableCommit()
データベースに対する永続コミット操作を実行します。永続コミット操作により、インメモリー・トランザクション・ログ・バッファがディスクにフラッシュされます。このメソッドでは、TimesTen組込みプロシージャttDurableCommitがコールされます。
詳細は、『Oracle TimesTen In-Memory Databaseリファレンス』のttDurableCommitに関する説明を参照してください。
void GetTTContext(char* output)
各データベース接続に一意な値である接続のコンテキスト値を返します。接続のコンテキストは、たとえば、TimesTenのttStatusユーティリティを使用し、TimesTen接続をPID(プロセスID)と関連付けるために使用できます。
コンテキスト値は、outputパラメータを介して返されます(CHAR[17]以上の配列が必要です)。
このメソッドにより、TimesTen組込みプロシージャttContextがコールされます。詳細は、『Oracle TimesTen In-Memory Databaseリファレンス』のttContextに関する説明を参照してください。
bool isConnected()
オブジェクトが(Connect()メソッドによって)TimesTenに接続されている場合はTRUE、そうでない場合はFALSEを返します。
void Rollback()
トランザクションをロールバック(取消)します。最後のCommit()またはRollback()へのコールの後に、この接続を介して行われたデータベースの変更は取り消されます。エラーが発生するとTTStatusオブジェクトが例外としてスローされます。「Commit()」も参照してください。
void SetAutoCommitOff()
接続の自動コミットを無効にします。後述のメソッドSetAutoCommitOn()も参照してください。
TimesTenは自動コミットが無効の場合にのみ最適なパフォーマンスで実行されるため、このメソッドはTTConnection::Connect()によって自動的にコールされます。
自動コミットが無効の場合、SELECT文をコミットするには、TTCmd::Close()を明示的にコールする必要があることに注意してください。
void SetAutoCommitOn()
接続の自動コミットを有効に設定します(つまり、すべてのSQL文を独自のトランザクションで実行します)。前述のメソッドSetAutoCommitOff()も参照してください。
TimesTenは、自動コミットが無効の場合、より迅速に実行されるので、SetAutoCommitOn()は一般的には推奨されません。
void SetIsoReadCommitted()
接続のトランザクション分離レベルをTXN_READ_COMMITTEDに設定します。コミット読取り分離レベルは、単一トランザクションのパフォーマンスと複数接続の優れた同時実行性という最善の組合せを提供します。後述のメソッドSetIsoSerializable()も参照してください。
void SetIsoSerializable()
接続のトランザクション分離レベルをTXN_SERIALIZABLEに設定します。通常、シリアライズ可能分離レベルは個別のトランザクションでは優れたパフォーマンスを提供しますが、同時実行性はきわめて低下します。ほぼすべての状況下で、シリアライズ可能分離レベルよりもコミット読取り分離レベルの方が適切です。前述のメソッドSetIsoReadCommitted()も参照してください。
void SetLockWait(int secs)
TimesTen組込みプロシージャttLockWaitをパラメータ(secs)付きでコールして、接続のロック・タイムアウト時間を設定します。一般的には、ほとんどのアプリケーションでロックのタイムアウトには2秒または3秒で十分です。デフォルトのロック・タイムアウト時間は10秒です。
詳細は、『Oracle TimesTen In-Memory Databaseリファレンス』のttLockWaitに関する説明を参照してください。
void SetPrefetchCloseOff()
TT_PREFETCH_CLOSE接続オプションを無効にします。後述のメソッドSetPrefetchCloseOn()も参照してください。
void SetPrefetchCloseOn()
TT_PREFETCH_CLOSE接続オプションをオンにします(これは、クライアント/サーバー・アプリケーションでのシリアライズ可能トランザクションのSELECT問合せパフォーマンスを最適化する場合に便利です)。この方法は、TimesTenに直接接続するアプリケーションには何もメリットがないことに注意してください。前述のメソッドSetPrefetchCloseOff()も参照してください。
『Oracle TimesTen In-Memory Databaseオペレーション・ガイド』のシリアライズ可能なトランザクションに対するTT_PREFETCH_CLOSEの有効化に関する説明を参照してください。
void SetPrefetchCount(int numrows)
TimesTen ODBCドライバがSELECT文に対して内部で一度にフェッチする行数を、クライアント/サーバー・アプリケーションによって調整できます。numrowsの値の範囲は1から128である必要があります。
この方法は、TimesTenに直接接続するアプリケーションには何もメリットがないことに注意してください。
|
注意: このメソッドは、TTCmd::FetchNext()を複数回実行することと同等ではありません。そのかわりに、このパラメータを適切に使用すると、TTCmd::FetchNext()の各コールにかかる時間が短縮されます。 |
TT_PREFETCH_COUNTの詳細は、『Oracle TimesTen In-Memory Database C開発者ガイド』の複数行のデータのプリフェッチに関する説明を参照してください。
TTConnectionPoolクラスは、マルチスレッド・アプリケーションによって、接続のプールの管理に使用されます。
通常、マルチスレッド・アプリケーションは次のいずれかの方法を使用して作成します。
スレッドの数が相対的に少なく、さらにスレッドの存続時間が長い場合は、アプリケーションの存続期間中使用される、異なる接続に各スレッドを割り当てることができます。この使用例では、TTConnectionPoolクラスは必要ありません。
プロセス内のスレッドの数が多い場合、またはスレッドの存続時間が短い場合は、アイドル状態の接続のプールを確立します。これらの接続は、アプリケーションの存続期間使用されます。スレッドは、データベース・トランザクションを実行する必要がある場合、プールからアイドル状態の接続を確認し、そのトランザクションを実行して、接続をプールに返します。これは、TTConnectionPoolクラスを使用した使用例です。
コンストラクタには2種類の形式があります。
TTConnectionPool()
または
TTConnectionPool(const int size);
ここで、sizeはプールの最大接続数を指定します。これを指定しないと、最大接続数は128です。size設定を指定し、TimesTenのConnections属性に設定されている最大接続数よりも大きな値を指定した場合、接続数がConnectionsの値を超えるとエラーが発生することに注意してください。『Oracle TimesTen In-Memory Databaseリファレンス』の接続に関する説明を参照してください。
|
注意: 全体のパフォーマンスを最高にするには、データベース・サーバーのCPUごとにデータベースへの同時直接接続が1つか2つあるようにすることが推奨されます。同時直接接続の数(接続プールのサイズ)は、データベース・サーバーのCPU数の2倍は超えないようにしてください。ただし、クライアント/サーバー接続では、CPUごとにさらに多くの接続が効率的にサポートされます。 |
アプリケーションは、TTConnectionPoolクラスを使用するために、クラスの単一のインスタンスを作成します。その後、TTConnectionクラスまたはユーザー・クラスのいずれかのインスタンスであるTTConnectionを拡張するオブジェクトをいくつか作成しますが、これではそのConnect()メソッドは直接にはコールしません。かわりに、アプリケーションではTTConnectionPool::AddConnectionToPool()メソッドを使用し接続オブジェクトをプールに配置し、その後TTConnectionPool::ConnectAll()をコールし、TimesTenへのすべての接続を確立します。バックグラウンドでは、ConnectAll()が、そのConnect()メソッドをコールするためにすべてのTTConnectionオブジェクト間をループします。
TimesTenアプリケーションのスレッドは、getConnection()メソッドとfreeConnection()メソッドを使用し、アイドル状態の接続を取得および返します。
「TTCmd、TTConnectionおよびTTConnectionPoolの使用」も参照してください。
|
重要: TTConnectionPoolを使用しTTConnectionを拡張する場合、コール・シーケンスにがあるTTConnection::Connect()メソッドは、(対応するTTConnectionPool::ConnectAll()メソッドがないため)オーバーライドしないようにする必要があります。かわりに、次のいずれかのConnect()メソッドをオーバーライドします。
virtual void Connect(const char* connStr) virtual void Connect(const char* connStr, const char* username, const char* password) その後、適切な対応する |
データベースに接続する権限は、CREATE SESSION権限を使用して、直接またはPUBLICロールを介してユーザーに付与する必要があります。「接続のアクセス制御」を参照してください。
| メソッド | 説明 |
|---|---|
AddConnectionToPool() |
TTConnectionオブジェクト(おそらくはTTConnectionから導出されたクラスのオブジェクト)を接続プールに追加します。 |
ConnectAll() |
すべてのTTConnectionオブジェクトを同時にTimesTenに接続します。 |
DisconnectAll() |
接続プール内のすべての接続をTimesTenから切断します。 |
freeConnection() |
別のスレッドへの再割当てができるよう、接続をプールに返します。 |
getConnection() |
スレッドの接続プールからアイドル状態の接続を確認します。 |
getStats() |
TTConnectionPoolオブジェクトに接続プールのステータス情報を問い合せます。 |
int AddConnectionToPool(TTConnection* connP)
このメソッドは、TTConnectionオブジェクト(おそらくはTTConnectionから導出されたクラスのオブジェクト)を接続プールに追加するために使用します。エラーがない場合は、-1が返されます。「freeConnection()」も参照してください。
void ConnectAll(const char* connStr) void ConnectAll(const char* connStr, const char* username, const char* password)
AddConnectionToPool()によってアプリケーションのすべてのTTConnectionオブジェクトが接続プールに追加された後、ConnectAll()メソッドを使用して、すべてのTTConnectionオブジェクトを同時にTimesTenに接続できます。connStrパラメータで指定された接続文字列を使用して接続が作成されます。ユーザーとパスワードを、接続文字列の一部または別のパラメータとして指定します。次のメソッドDisconnectAll()も参照してください。
エラーが発生するとTTStatusオブジェクトが例外としてスローされます。
データベースに接続する権限は、CREATE SESSION権限を使用して、直接またはPUBLICロールを介してユーザーに付与する必要があります。「接続のアクセス制御」を参照してください。
void DisconnectAll()
接続プール内のすべての接続をTimesTenから切断します。前述のメソッドConnectAll()も参照してください。
アプリケーションでは、プロセス障害の分析とリカバリに関連するオーバーヘッドを回避するために、終了の前にDisconnectAll()をコールする必要があります。エラーが発生するとTTStatusオブジェクトが例外としてスローされます。
void freeConnection(TTConnection* connP)
別のスレッドへの再割当てができるよう、接続をプールに返します。アプリケーションでは、トランザクション中の接続を解放しないでください。TTConnection::Commit()またはRollback()は、TTConnectionオブジェクトがfreeConnection()に渡される直前にコールされる必要があります。「AddConnectionToPool()」も参照してください。
TTConnection* getConnection(int timeout_millis=0)
接続プールからスレッドで使用するアイドル状態の接続があるかを確認します。アイドル状態のTTConnectionオブジェクトへのポインタが返されます。スレッドはその後、トランザクションを実行し、Commit()またはRollback()のいずれかでそれを終了してから、freeConnection()メソッドを使用して接続をプールに返します。
プール内にアイドル状態の接続がない場合は、freeConnection()のコールによって接続がプールに返されるまで、getConnection()をコールするスレッドがブロックされます。オプションのタイムアウトをミリ秒単位で指定できます。これが指定された場合、getConnection()は、最大でtimeout_millisミリ秒間、使用可能な接続を待機します。その時間内に使用可能な接続がなかった場合、getConnection()はコール元にNULLを返します。
void getStats(int* nGets, int* nFrees, int* nWaits, int* nTimeouts, int* maxInUse, int* nForcedCommits)
TTConnectionPoolにステータス情報を問い合せます。次のデータが返されます。
nGets: getConnection()に対するコール数
nFrees: freeConnection()に対するコール数
nWaits: 接続が返されるまでgetConnection()に対するコールが待機する必要があった回数
nTimeouts: タイムアウトしたgetConnection()に対するコール数
maxInUse: 同時に使用された接続の最大数の最高水準
nForcedCommits: freeConnection()によって接続がプールにチェックインされる前に、その接続に対してCommit()をコールする必要があった回数
このカウンタが0(ゼロ)以外の場合は、ユーザー・アプリケーションが接続をプールに返す前にTTConnection::Commit()またはRollback()をコールしていません。
TTCmdオブジェクトは、アプリケーション・プログラムで複数回使用される単一のSQL文をカプセル化します。TTCmdは、ODBC文(SQLHSTMT)ハンドルの付加価値C++ラッパーとみなすことができます。
TTCmdには、次の3種類のパブリック・メソッドがあります。
プログラムで複数回実行される各SQL文には、独自のTTCmdオブジェクトが必要です。これらのTTCmdオブジェクトは、プログラムの初期化時にそれぞれ1回準備され、プログラムの実行時にExecute()メソッドで複数回実行されます。
ExecuteImmediate()メソッドは、少数回のみ実行する必要のあるデータベース操作でのみ使用します。ExecuteImmediate()はどのタイプのSELECT文とも互換性がないことに注意してください。かわりに、すべての問合せでPrepare()とExecute()を使用する必要があります。また、ExecuteImmediate()は、後で、挿入、更新または削除された行数を調べるために、getRowcount()を使用してポーリングされるINSERT、UPDATEまたはDELETE文とも互換性がありません。これらの制限は、一部の特別な状況(表の作成または削除など)を除き、ExecuteImmediate()の使用を避けるために課されています。
「TTCmd、TTConnectionおよびTTConnectionPoolの使用」も参照してください。
|
注意: 基礎となるODBC文を直接操作する必要がある場合は、TTCmd::getHandle()メソッドを使用してください。 |
TimesTenには、表、ビュー、マテリアライズド・ビュー、順序およびシノニムなどのデータベース・オブジェクトについて、オブジェクトレベルの解決法でデータベース・アクセスを制御する機能が含まれています。「アクセス制御に関するTimesTen機能の考慮事項」を参照してください。
| メンバー | 説明 |
|---|---|
TTCMD_PARAM_INPUTOUTPUT_TYPE |
これは、パラメータの登録時、そのパラメータが入力、出力または入力/出力のどれかを指定するために使用します。サポートされる値は、PARAM_IN、PARAM_INOUTおよびPARAM_OUTです。「パラメータの登録」を参照してください。 |
| メソッド | 説明 |
|---|---|
Close() |
アプリケーションでの行のフェッチが終了したら、結果セットを閉じます。 |
Drop() |
準備済のSQL文とそれに関連付けられたすべてのリソースを解放します。 |
Execute() |
実行のために準備されたSQL文を起動します。 |
ExecuteImmediate() |
事前に準備されていないSQL文を起動します。 |
FetchNext() |
結果セットの行を1行ずつフェッチします。行のフェッチに成功した場合は0を、フェッチする行がなくなった場合は1を返します。 |
getColumn() |
結果セットの現在の行の指定した列の値を取得します。 |
getColumnLength() |
指定された列の長さをバイト単位で返します。 |
getColumnNullable() |
結果セットの現在の行の指定した列の値を取得し、値がNULL値であるかどうかを示すブールを返します。 |
getHandle() |
基礎となるODBC文ハンドルを取得します。 |
getMaxRows() |
SELECT文によって返される行の数の現在の制限を返します。 |
getNextColumn() |
結果セットの現在の行の次の列の値を取得します。 |
getNextColumnNullable() |
結果セットの現在の行の次の列の値を取得し、値がNULL値であるかどうかを示すブールを返します。 |
getParam() |
準備済のSQL文の実行後、各コールは指定した出力または入力/出力パラメータの出力値を取得します。 |
getQueryThreshold() |
問合せのしきい値を取得します。 |
getRowCount() |
最近実行されたSQL操作の影響を受けた行の数を返します。 |
isColumnNull() |
現在の列の指定した行値がNULLであるかどうかを示します。 |
Prepare() |
SQL文とTTCmdオブジェクトを関連付けます。 |
printColumn() |
現在の行の指定した列の値を出力ストリームに出力します。 |
registerParam() |
バインド用にパラメータを登録します。これは、入力または入力/出力パラメータで必要です。 |
RePrepare() |
準備済文の文ハンドルが無効化された場合、これによって文を再準備できます。 |
setMaxRows() |
SELECT文によって返される行の数に制限を設定します。 |
setParam() |
準備済のSQL文を実行する前に、各コールは指定したパラメータの値を設定します。 |
setParamLength() |
指定した入力パラメータの長さをバイト単位で設定します。 |
setParamNull() |
準備済のSQL文を実行する前にパラメータの値をNULLに設定します。 |
setQueryThreshold() |
各SQL文の実行時間制限のしきい値を設定します。これを超過した場合、サポート・ログに警告が書き込まれ、SNMPトラップがスローされます。 |
setQueryTimeout() |
SQL文のタイムアウト値を設定します。 |
void Close()
Execute()メソッドを使用してSQL SELECT文を実行すると、結果セットから行をフェッチするために使用できるカーソルがオープンされます。アプリケーションが結果セットから行をフェッチし終えたら、Close()メソッドを使用してクローズする必要があります。
結果セットを閉じることに失敗すると、行のロックが保持される時間が長くなりすぎるため、同時実行性の問題、メモリー・リークおよびその他のエラーが発生する可能性があります。
エラーが発生するとTTStatusオブジェクトが例外としてスローされます。
void Drop()
準備済のSQL文を今後使用しない場合は、Drop()メソッドをコールして、その文とそれに関連付けられたリソースを解放できます。再度Prepare()をコールすると、TTCmdオブジェクトを別の文に再利用できます。
複数のTTCmdオブジェクトを使用して複数のSQL文を実行した方が、より効率的です。特定のSQL文を今後使用しない場合にのみ、Drop()メソッドを使用してください。
エラーが発生するとTTStatusオブジェクトが例外としてスローされます。
void Execute()
setParam()コールで必要なパラメータ値を定義後、このメソッドは、Prepare()メソッドを使用して実行されるよう事前準備されたSQL文を起動します。エラーが発生するとTTStatusオブジェクトが例外としてスローされます。
SQL文がSELECT文の場合は、このメソッドによって問合せが実行されますが、結果セットから行が返されません。FetchNext()メソッドを使用すると、結果セットから一度に1行ずつフェッチされます。該当するすべての行がフェッチされたら、Close()メソッドを使用して結果セットを閉じます。SELECT以外のSQL文の場合は、カーソルがオープンされないため、Close()メソッドをコールする必要はありません。
TimesTenには、表、ビュー、マテリアライズド・ビュー、順序およびシノニムなどのデータベース・オブジェクトについて、オブジェクトレベルの解決法でデータベース・アクセスを制御する機能が含まれています。アクセス制御の権限は、データベースでSQLが準備されるときと実行されるときの両方で確認され、パフォーマンス・コストの大部分は準備時に発生します。「アクセス制御に関するTimesTen機能の考慮事項」を参照してください。
int ExecuteImmediate(TTConnection* cP, const char* sqlp)
このメソッドは、事前に準備されていないSQL文を起動します。
少数回のみ実行されるSQL文については、Prepare()およびExecute()のかわりにExecuteImmediate()を使用すると便利です。DDL文(CREATE TABLE、DROP TABLEなど)や、使用頻度が低く結果セットを返さないDML文(DELETE FROM table_nameなど)にExecuteImmediate()を使用します。
ExecuteImmediate()は、結果セットを返すSQL文と互換性がありません。また、ExecuteImmediate()によって実行された文は、後でgetRowCount()(DML操作によって影響を受けた行の数を取得する)を使用して問い合せることができません。このため、ExecuteImmediate()は自動的にgetRowCount()をコールし、その値がこのメソッドの整数の戻り値となります。
エラーが発生するとTTStatusオブジェクトが例外としてスローされます。
int FetchNext()
Execute()メソッドを使用して準備済のSQL SELECT文を実行した後、FetchNext()メソッドを使用して、結果セットから一度に1行ずつフェッチします。
結果セットから1行をフェッチした後に、オーバーロードされた適切なgetColumn()メソッドを使用して、現在の行から値をフェッチします。
結果セットに行がなくなると、FetchNext()は1を返します。行が返されると、FetchNext()は0を返します。
Execute()メソッドを使用してSELECTを実行した後、要求されるすべての行がフェッチされてから、Close()メソッドで結果セットを閉じる必要があります。Close()メソッドをコールした後は、FetchNext()メソッドを使用して結果セットからそれ以上の行をフェッチできないことに注意してください。
エラーが発生するとTTStatusオブジェクトが例外としてスローされます。
void getColumn (int cno, TYPE* valueP) void getColumn (int cno, TYPE* valueP, int* byteLenP)
getColumn()メソッドおよびgetColumnNullable()メソッドでは、結果セットの現在の行の列の値をフェッチできます。getColumn()またはgetColumnNullable()をコールする前に、FetchNext()メソッドをコールして、SELECT文の結果セットの次の(または最初の)行をフェッチする必要があります。SQL文はExecute()メソッドを使用して実行されます。
各getColumn()コールは、特定の列に関連付けられた値を返します。列は序数で参照され、1はSELECT文で指定された最初の列を示します。すべての場合において、getColumn()メソッドに渡される最初の引数cnoは、値がフェッチされる列の序数です。2番目の引数valuePは、指定された列の値を保存する変数のポインタです。この引数の型は、返される列の型に依存します。表に示すとおり、NCHAR、NVARCHARおよびバイナリ型については、メソッド・コールでbyteLenPを指定します(これは、valuePバッファに書き込まれるバイト数の整数値へのポインタです)。
TTClassesライブラリは、大規模なデータ型の変換セットをサポートしません。準備済のSQLの出力列ごとに、適切なバージョンのgetColumn()をコールする必要があります。誤ったバージョンをコールする(たとえば、整数の列をchar*値にフェッチしようとする)と、例外がスローされます(TTStatusオブジェクト)。
NUMBER列から整数型のデータをフェッチする場合、getColumn()では、SQLTINYINT、SQLSMALLINT、SQLINTEGERおよびSQLBIGINTのバージョンがサポートされています。これらは、スケール・パラメータが0に設定された、NUMBER(p)またはNUMBER(p,0)などのNUMBERフィールドのみに適しています。前述の関数の精度範囲を次に示します。
| 関数 | 精度範囲 |
|---|---|
SQLTINYINT |
0<=p<=2 |
SQLSMALLINT |
0<=p<=4 |
SQLINTEGER |
0<=p<=9 |
SQLBIGINT |
0<=p<=18 |
アプリケーションがデータベースから情報を取得するために使用する変数に列内のすべての値が収まるようにするには、データ型NUMBER(p)のすべての表列に対してSQLBIGINTを使用します(ここで、0 <= p <= 18です)。次に例を示します。
getColumn(int cno, SQLBIGINT* iP)
表3-2には、サポートされるTimesTenの列型と、各パラメータ型での使用に適したgetColumn()とgetColumnNullable()のバージョンを示します。
表3-2 サポートされるTimesTenの表の列型のgetColumn()のバージョン
| データ型 | サポートされるgetColumn()のバージョン |
|---|---|
|
|
getColumn(cno, SQLTINYINT* iP) |
|
|
getColumn(cno, SQLSMALLINT* iP) |
|
|
getColumn(cno, SQLINTEGER* iP) |
|
|
getColumn(cno, SQLBIGINT* iP) |
|
|
getColumn(cno, float* fP) |
|
|
getColumn(cno, double* dP) |
|
|
getColumn(cno, char** cPP) getColumn(cno, char* cP) getColumn(cno, SQLTINYINT* iP) getColumn(cno, SQLSMALLINT* iP) getColumn(cno, SQLINTEGER* iP) getColumn(cno, SQLBIGINT* iP) 注意: |
|
|
getColumn(cno, char** cPP) getColumn(cno, char* cP) 注意: |
|
|
getColumn(cno, SQLWCHAR** wcPP) getColumn(cno, SQLWCHAR** wcPP, byteLenP) 注意: オプションで、返される値のバイト数に関する |
|
|
getColumn(cno, void** binPP, byteLenP) getColumn(cno, void* binP, byteLenP) 注意: |
|
|
getColumn(cno, TIMESTAMP_STRUCT* tsP) |
|
|
getColumn(cno, DATE_STRUCT* dP) |
|
|
getColumn(cno, TIME_STRUCT* tP) |
このリリースのTTClassesライブラリでは、他のTimesTen表列型はサポートされていません。
int getColumnLength(int cno)
NULL終了文字はカウントされない、現在の行の列番号cnoの値の長さをバイト単位で返します。また、値がNULLの場合はSQL_NULL_DATAが返されます。(ODBCに精通している場合、これはSQLFetchへのコール後SQLBindColから最後のパラメータpcbValueにODBCによって保存される値です。)NULLでない値がある場合、0から行の精度の間の長さが返されます。「getColumnPrecision()」を参照してください。
たとえば、VARCHAR2(25)列を考えてみてください。この値がNullの場合、返される長さは-1になります。この値がabcdeの場合、返される長さは5になります。
このメソッドは、CHAR、VARCHAR2、NCHAR、NVARCHAR2、BINARYおよびVARBINARY型の列にアクセスする場合のみ通常役立ちます。
bool getColumnNullable(int cno, TYPE* valueP) bool getColumnNullable(int cno, TYPE* valueP, int* byteLenP)
getColumnNullable()メソッドはgetColumn()メソッドと類似しており、前述の表3-2のとおり同じデータ型およびシグネチャをサポートしています。ただし、getColumnNullable()メソッドはgetColumn()の動作に加え、値がSQLのNULL疑似値であるかどうかを示すブールを返します。値がNULLである場合、2番目のパラメータは特徴的な値(-9999など)に設定され、メソッドの戻り値はTRUEとなります。値がNULLでない場合、2番目のパラメータが指す変数を介して値は返され、getColumnNullable()メソッドによってFALSEが返されます。
int getMaxRows()
このメソッドは、SELECT文によってこのTTCmdオブジェクトから返される行数について現在設定されている上限を返します。戻り値0は、すべての行が返されることを示します。「setMaxRows()」も参照してください。
void getNextColumn(TYPE* valueP) void getNextColumn(TYPE* valueP, int* byteLenP)
getNextColumn()メソッドおよびgetNextColumnNullable()メソッドでは、結果セットの現在の行の次の列の値がフェッチされます。getNextColumn()またはgetNextColumnNullable()をコールする前に、FetchNext()メソッドをコールして、SELECT文の結果セットの次の(または最初の)行をフェッチする必要があります。getNextColumn()を使用する場合、列は順番にフェッチされます。フェッチする順番は変更できません。
サポートされるSQLのデータ型および各データ型の適切なメソッド・バージョンについては、表3-2を参照してください。この情報は、getNextColumn()に使用できますが、getNextColumn()には列番号パラメータはありません。
bool getNextColumnNullable(TYPE* valueP) bool getNextColumnNullable(TYPE* valueP, int* byteLenP)
getNextColumnNullable()メソッドは、getNextColumn()メソッドに類似しています。ただし、getNextColumnNullable()メソッドはgetNextColumn()の動作に加え、値がSQLのNULL疑似値であるかどうかを示すブールを返します。値がNULLである場合、2番目のパラメータは特徴的な値(-9999など)に設定され、メソッドの戻り値はTRUEとなります。値がNULLでない場合、2番目のパラメータが指す変数を介して値が返され、メソッドはFALSEを返します。getNextColumnNullable()を使用する場合、列は順番にフェッチされます。フェッチする順番は変更できません。
サポートされるSQLのデータ型および各データ型の適切なメソッド・バージョンについては、表3-2を参照してください。この情報は、getNextColumnNullable()に使用できますが、getNextColumnNullable()には列番号パラメータはありません。
bool getParam(int pno, TYPE* valueP) bool getParam(int pno, TYPE* valueP, int* byteLenP)
各getParam()バージョンは、準備済のSQL文の実行後、パラメータ番号で指定した出力または入力/出力パラメータの値を取得するために使用します。SQL文は、使用前にPrepare()メソッドで準備され、Execute()メソッドで実行されます。getParam()メソッドは、文の実行後、各出力パラメータに適切なデータ型の変数を提供するために使用します。
getParam()に最初に渡される引数は、出力値のパラメータの位置です。SQL文の最初のパラメータはパラメータ1です。getParam()に2番目に渡される引数は、出力値の変数です。オーバーロードされたバージョンのgetParam()は、2番目の引数で様々なデータ型を受け入れます。
getParam()メソッドは、表3-2のgetColumn()で説明しているものと同じデータ型をサポートしています。表に示すとおり、NCHAR、NVARCHARおよびバイナリ型については、メソッド・コールでbyteLenPを指定します(これは、パラメータ値内のバイト数の整数値へのポインタです)。
getParam()では、パラメータ値がNULLの場合はTRUEを返し、それ以外の場合はFALSEを返します。
TTClassesライブラリは、大規模なデータ型の変換セットをサポートしません。準備済のSQLの出力パラメータごとに、オーバーロードされた適切なバージョンのgetParam()をコールする必要があります。誤ったバージョンをコールする(たとえば、整数パラメータをchar*値に使用しようとする)と、プログラム障害が発生するおそれがあります。
getParam()の使用方法の詳細は、「出力または入力/出力パラメータのバインド」を参照してください。
REF CURSORについては、REF CURSOR(データ型SQL_REFCURSOR)の文ハンドルとしてTTCmdオブジェクトを使用できるよう、次のシグネチャがサポートされています。情報および例については、「REF CURSORの使用」を参照してください。
bool getParam(int pno, TTCmd** rcCmd)
int getQueryThreshold()
「setQueryThreshold()」で説明した、TTCmdオブジェクトのしきい値を返します。
setQueryThreshold()で値が設定されていない場合、このメソッドはODBC接続オプションTT_QUERY_THRESHOLD(設定されている場合)の値またはTimesTenの一般接続属性QueryThresholdを返します。
int getRowCount()
このメソッドをExecute()の直後にコールして、実行されたSQL操作の影響を受けた行の数を返すことができます。たとえば、10行を削除するDELETE文が実行された後には、getRowCount()は10を返します。
bool isColumnNull(int cno)
このメソッドでも、現在の行の列番号cnoの値がNULLであるかどうかを判断できます(そうである場合はTRUE、そうでない場合はFALSEを返します)。
「getColumnNullable()」メソッドの情報も参照してください。
void Prepare(TTConnection* cP, const char* sqlp)
このメソッドは、SQL文とTTCmdオブジェクトを関連付けます。2つのパラメータを使用します。
TTConnectionオブジェクトへのポインタ
TTConnection::Connect()をコールし、接続オブジェクトをデータベースに接続する必要があります。
準備されているSQL文のconst char*パラメータ
TimesTenには、表、ビュー、マテリアライズド・ビュー、順序およびシノニムなどのデータベース・オブジェクトについて、オブジェクトレベルの解決法でデータベース・アクセスを制御する機能が含まれています。アクセス制御の権限は、データベースでSQLが準備されるときと実行されるときの両方で確認され、パフォーマンス・コストの大部分は準備時に発生します。「アクセス制御に関するTimesTen機能の考慮事項」を参照してください。
void printColumn(int cno, STDOSTREAM& os, const char* nullString) const
このメソッドでは、出力ストリームosに現在の行の列番号値cnoを出力します。これは、デバッグまたはデモ・プログラム用に使用します。nullStringでは、列値がNULLの場合(たとえばNULLまたは?)の場合、何を出力するかを指定します。
void registerParam(int pno, TTCMD_PARAM_INPUTOUTPUT_TYPE inputOutputType, int sqltype) void registerParam(int pno, TTCMD_PARAM_INPUTOUTPUT_TYPE inputOutputType, int sqltype, int precision) void registerParam(int pno, TTCMD_PARAM_INPUTOUTPUT_TYPE inputOutputType, int sqltype, int precision, int scale)
このメソッドは、バインド用のパラメータを登録するために使用します。これは出力および入力/出力パラメータで必要で、SQLデータ型、精度(該当する場合、データ型で使用される最大桁数)、スケール(該当する場合、小数点以下の最大桁数)を必要に応じて指定するためにも使用できます。「パラメータの登録」を参照してください。
void RePrepare(TTConnection* cP)
このメソッドは文を再準備します。これは、SQL文が参照する表が変更されたなど、準備済文の文ハンドルが無効の場合にのみ有効です。「Prepare()」も参照してください。
void setMaxRows(const int nMaxRows)
このメソッドは、SELECT文によって返される行数に制限を設定します。結果セット内の行数が設定された上限を超過すると、リクエストされた設定サイズの最後の行のフェッチ後にTTCmd::FetchNext()メソッドによって1が返されます。「getMaxRows()」も参照してください。
デフォルトでは、すべての行が返されます。すべての行を返すように制限をリセットするには、nMaxRowsを0に設定してsetMaxRows()をコールします。この制限はSELECT文に対してのみ意味があります。
void setParam(int pno, TYPE value) void setParam(int pno, TYPE* valueP) void setParam(int pno, TYPE* valueP, int byteLen)
この項では、オーバーロードされたすべてのsetParam()バージョンについて説明します。
各setParam()バージョンは、準備済のSQL文を実行する前に、パラメータ番号で指定したパラメータの値を設定するために使用されます。SQL文は、使用前にPrepare()メソッドで準備され、Execute()メソッドで実行されます。SQL文にパラメータ・マーカー(リテラル定数が有効である位置で使用される?文字)が含まれている場合、そのSQL文を実行するには、それらのパラメータに値を割り当てる必要があります。文を実行する前に、setParam()メソッドを使用して各パラメータの値を定義します。詳細は、『Oracle TimesTen In-Memory Database SQLリファレンス・ガイド』の動的パラメータに関する説明を参照してください。
setParam()に最初に渡される引数は、設定されるパラメータの位置です。SQL文の最初のパラメータはパラメータ1です。setParam()に2番目に渡される引数はパラメータの値です。オーバーロードされたバージョンのsetParam()は、2番目の引数で様々なデータ型を受け入れます。
TTClassesライブラリは、大規模なデータ型の変換セットをサポートしません。準備済のSQLのパラメータごとに、オーバーロードされた適切なバージョンのsetParam()をコールする必要があります。誤ったバージョンをコールする(たとえば、整数パラメータをchar*値に設定しようとする)と、プログラム障害が発生するおそれがあります。
setParam()に渡された値は、TTCmdオブジェクトによってメンテナンスされる内部バッファにコピーされます。これらのバッファは静的に割り当てられ、Prepare()メソッドによってバインドされます。パラメータ値はsetParam()のコール時にsetParam()に渡される値であって、後続のExecute()メソッドのコール時の値ではありません。
表3-3に、サポートされるSQLデータ型と、各型での使用に適したsetParam()のバージョンを示します。表に示されていないSQLデータ型は、このバージョンのTTClassesではサポートされていません。表に示すとおり、NCHAR、NVARCHARおよびバイナリ型については、メソッド・コールでbyteLenを指定します(これは、パラメータ値内のバイト数の整数値です)。
setParam()の使用方法の詳細は、「入力パラメータのバインド」および「出力または入力/出力パラメータのバインド」を参照してください。重複するパラメータおよびTimesTenモードとOracleモードでのその処理の違いの詳細は、「重複パラメータのバインド」を参照してください。
|
注意:
|
表3-3 サポートされるTimesTenの表の列型のsetParam()のバージョン
| データ型 | サポートされるsetParam()のバージョン |
|---|---|
|
|
setParam(pno, SQLTINYINT value) |
|
|
setParam(pno, SQLSMALLINT value) |
|
|
setParam(pno, SQLINTEGER value) |
|
|
setParam(pno, SQLBIGINT value) |
|
|
setParam(pno, float value) |
|
|
setParam(pno, double value) |
|
|
setParam(pno, char* valueP) setParam(pno, const char* valueP) setParam(pno, SQLCHAR* valueP) setParam(pno, SQLTINYINT value) setParam(pno, SQLSMALLINT value) setParam(pno, SQLINTEGER value) setParam(pno, SQLBIGINT value) 注意: 整数のバージョンは、たとえば |
|
|
setParam(pno, char* valueP) setParam(pno, const char* valueP) setParam(pno, SQLCHAR* valueP) |
|
|
setParam(pno, SQLWCHAR* valueP, byteLen) |
|
|
setParam(pno, const void* valueP, byteLen) |
|
|
setParam(pno, TIMESTAMP_STRUCT* valueP) |
|
|
setParam(pno, DATE_STRUCT* valueP) |
|
|
setParam(pno, TIME_STRUCT* valueP) |
(バッチ以外の操作バージョン)
void setParamLength(int pno, int byteLen)
準備済文の実行前に、パラメータ番号で指定した入力パラメータのバインド後の値の長さをバイト単位で設定します。
(バッチ以外の操作バージョン)
void setParamNull(int pno)
パラメータ番号で指定したバインドされた入力パラメータにSQL NULLの値を設定します。
void setQueryThreshold(const int nSecs)
このメソッドは、TTCmdオブジェクトの時間制限のしきい値を秒単位で指定するために使用します。(これは、問合せだけでなく、すべてのSQL文に使用できます。)文の実行時間がしきい値を超過した場合、サポート・ログに警告が書き込まれ、SNMPトラップがスローされます。実行は継続され、しきい値による影響は受けません。「getQueryThreshold()」も参照してください。
setQueryThreshold()メソッドは、TT_QUERY_THRESHOLDまたはTimesTenの一般接続属性QueryThresholdを設定するSQLSetStmtOptionを使用するのと同じ効果があります。
「SQL文の実行に対するタイムアウトまたはしきい値の設定」を参照してください。
void setQueryTimeout(const int nSecs)
このメソッドは、(問合せだけではなく)すべてのSQL文の実行時、タイムアウトまでの長さを秒単位で指定するために使用します。デフォルトでは、タイムアウトはありません。
これは、SQL_QUERY_TIMEOUTまたはTimesTenの一般接続属性SqlQueryTimeoutを設定するためにSQLSetStmtOptionを使用するのと同じ効果があります。
「SQL文の実行に対するタイムアウトまたはしきい値の設定」を参照してください。
準備済のTTCmdオブジェクトの、バインドされた入力パラメータおよび出力列のプロパティについて問い合せる場合に有効なメソッドがいくつかあります。通常、これらのメソッドでは、文が事前に準備されている場合にのみ、有効な結果が得られます。
| メソッド | 説明 |
|---|---|
getColumnName() |
指定された列の名前を返します。 |
getColumnNullability() |
指定した列のデータとして値NULLが可能かどうかを示します。 |
getColumnPrecision() |
指定された列の精度を返します。 |
getColumnScale() |
指定された列のスケールを返します。 |
getColumnType() |
指定された列のODBCデータ型を返します。 |
getNColumns() |
出力列の数を返します。 |
getNParameters() |
入力パラメータの数を返します。 |
getParamNullability() |
指定したパラメータの値としてNULLが可能かどうかを示します。 |
getParamPrecision() |
準備済の文に指定されたパラメータの精度を返します。 |
getParamScale() |
準備済の文に指定されたパラメータのスケールを返します。 |
getParamType() |
指定されたパラメータのODBCデータ型を返します。 |
isBeingExecuted |
TTCmdオブジェクトで表現された文が実行されたかどうかを示します。 |
int getColumnNullability(int cno)
列番号cnoとしてNULLデータが可能であるかどうかを示します。SQL_NO_NULLS、SQL_NULLABLEまたはSQLNULLABLE_UNKNOWNが返されます。
int getColumnPrecision(int cno)
列番号cno内のデータのデータベースの列サイズを参照する精度を返します。たとえば、VARCHAR2(25)列では、25の精度が返されます。
通常、この値は、表のCHAR、VARCHAR2、NCHAR、NVARCHAR2、BINARYおよびVARBINARY型の列から出力を生成する場合にのみ重要です。
int getColumnType(int cno)
列番号cnoのデータ型を返します。返される値は、sql.hに見られる、パラメータのODBC型(SQL_INTEGER、SQL_REAL、SQL_BINARY、SQL_CHARなど)です。その他のTimesTen ODBC型(SQL_WCHAR、SQL_WVARCHAR)は、TimesTenヘッダー・ファイルtimesten.hで見られます。
int getParamNullability(int pno)
パラメータ値pnoとして値NULLが可能かどうかを示します。SQL_NO_NULLS、SQL_NULLABLEまたはSQLNULLABLE_UNKNOWNが返されます。
|
注意: 以前のリリースでは、このメソッドではintではなくboolが返されました。 |
int getParamPrecision(int pno)
パラメータ番号pnoのそのデータ型で使用される最大桁数を参照する精度を返します。前述の「getColumnPrecision()」の情報も参照してください。
int getParamType(int pno)
パラメータ番号pnoのデータ型を返します。返される値は、sql.hに見られる、ODBC型(SQL_INTEGER、SQL_REAL、SQL_BINARY、SQL_CHARなど)です。その他のTimesTen型(SQL_WCHAR、SQL_WVARCHAR)は、TimesTenヘッダー・ファイルtimesten.hで見られます。
TimesTenは、挿入、更新および削除のバッチ操作のためにODBC関数SQLBindParamsをサポートします。TTClassesには、ODBC関数SQLBindParamsへのインタフェースが用意されています。
TTClassesでバッチ操作を実行する際の方法は、バッチ以外の操作を実行する場合と似ています。まずPrepareBatch()を使用してSQL文をコンパイルします。その後、その文の各パラメータを、BindParameter()を使用して値の配列にバインドします。最後にExecuteBatch()を使用して文を実行します。
バッチ操作の使用例については、TimesTenのクイック・スタートにあるサンプル・プログラムTTClasses bulktestを参照してください。「TimesTen TTClassesデモについて」を参照してください。
この項では、TTClassesユーザー向けに、バッチのINSERT、UPDATEおよびDELETE機能を公開するTTCmdメソッドについて説明します。
| メソッド | 説明 |
|---|---|
batchSize() |
バッチ内の文の数を返します。 |
BindParameter() |
PrepareBatch()を使用し、準備済文の1つのパラメータの値の配列をバインドします。 |
ExecuteBatch() |
PrepareBatch()によって実行のために準備されたSQL文を起動します。バッチ内の更新された行数を返します。 |
PrepareBatch() |
INSERT、UPDATEおよびDELETE文のバッチ処理を準備します。 |
setParamLength() |
準備済文の実行の前に、指定したバインド・パラメータの長さをバイト単位で設定します。 |
setParamNull() |
準備済文を実行の前に指定したバインド・パラメータの値をNULLに設定します。 |
void BindParameter(int pno, unsigned short batSz, TYPE* valueP) void BindParameter(int pno, unsigned short batSz, TYPE* valueP, size_t maxByteLen) void BindParameter(int pno, unsigned short batSz, TYPE* valueP, SQLLEN* userByteLenP, size_t maxByteLen)
オーバーロードされたBindParameter()メソッドは、PrepareBatch()によってコンパイルされたSQL文について、指定したパラメータをバインドするために使用されます。これによって、バッチ内で文が繰り返し実行される際に違う値を使用できます。pnoパラメータは、バインドするパラメータの文内の左から開始される位置(最初のパラメータは1で次は2と続きます)を示します。
重複するパラメータおよびTimesTenモードとOracleモードでのその処理の違いの詳細は、「重複パラメータのバインド」を参照してください。
このコールのbatSz(バッチ・サイズ)値は、PrepareBatch()に指定したbatSzと一致する必要があり、バインドされた配列には少なくともbatSzの数の値が含まれる必要があります。各パラメータの正しい型を判別する必要があります。指定されたパラメータ番号が無効であるか、指定したバッチ・サイズが一致しないか、またはデータ・バッファがnullの場合、TTStatusオブジェクトが例外としてスローされ、実行時エラーがTTClassesグローバル・ロギング機能にTTLog::TTLOG_ERRロギング・レベルで書き込まれます。
次の表3-4に、サポートされるSQLデータ型および各パラメータ型で使用するBindParameter()の適切なバージョンを示します。
ExecuteBatch()を起動するたびに、アプリケーションで事前にバインド配列に有効なパラメータ値を設定する必要があります。「setParamNull()」の説明のとおり、null値の設定にはsetParamNull()を使用できることに注意してください。(バッチ・モードでは、rownoを指定するsetParamNull()の2つのパラメータを使用するバージョンを使用する必要があります。パラメータを1つ使用するバージョンは、バッチ以外の用途のみで使用します。)
TT_CHAR、CHAR、TT_VARCHARおよびVARCHAR2のSQLデータ型については、BindParameter()コールに最大長のパラメータを追加する必要があります。
型size_tのmaxByteLenは、このパラメータ位置の任意の値(バイト単位)の最大長用です。
TT_NCHAR、NCHAR、TT_NVARCHAR、NVARCHAR2、BINARYおよびVARBINARYのSQLデータ型については、BindParameter()コールにパラメータ長および最大長の2つパラメータを追加する必要があります。
userByteLenPは、バッチ内のSQL文のこのパラメータ位置の各値の長さを指定する、バイト単位のSQLLENパラメータ長の配列です。この配列の長さには、batSzの長さ以上が必要であり、ExecuteBatch()のコール前に、有効な長さの値が設定されている必要があります。(null値の場合は、パラメータ長の配列に、setParamNull()バッチ・メソッドを使用する場合と同等のSQL_NULL_DATAを格納できます。)
maxByteLenは、前述の説明のとおりです。これは、userByteLenP配列の任意の要素に指定する値の最大長を示します。
userByteLenPを利用できないデータ型では(または利用できるが別の方法が必要な場合は)、オプションでデータ長の設定にsetParamLength()バッチ・メソッドを(「setParamLength()」を参照)、またnull値の設定にsetParamNull()バッチ・メソッドを(「setParamNull()」を参照)使用できます。
BindParameter()の使用方法の例の詳細は、次の例3-5の「ExecuteBatch()」を参照してください。
表3-4 サポートされるTimesTenの表の列型のBindParameter()のバージョン
| SQLデータ型 | サポートされるBindParameter()のバージョン |
|---|---|
|
|
BindParameter(pno, batSz, SQLTINYINT* user_tiP) |
|
|
BindParameter(pno, batSz, SQLSMALLINT* user_siP) |
|
|
BindParameter(pno, batSz, SQLINTEGER* user_iP) |
|
|
BindParameter(pno, batSz, SQLBIGINT* user_biP) |
|
|
BindParameter(pno, batSz, float* user_fP) |
|
|
BindParameter(pno, batSz, double* user_dP) |
|
|
BindParameter(pno, batSz, char** user_cPP, maxByteLen) |
|
|
BindParameter(pno, batSz, char** user_cPP, maxByteLen) |
|
|
BindParameter(pno, batSz, SQLWCHAR** user_wcPP, userByteLenP, maxByteLen) |
|
|
BindParameter(pno, batSz, const void** user_binPP, userByteLenP, maxByteLen) |
|
|
BindParameter(pno, batSz, TIMESTAMP_STRUCT* user_tssP) |
|
|
BindParameter(pno, batSz, DATE_STRUCT* user_dsP) |
|
|
BindParameter(pno, batSz, TIME_STRUCT* user_tsP) |
int ExecuteBatch(unsigned short numRows)
PrepareBatch()によってSQL文を準備し、そのSQL文の各パラメータに対してBindParameter()をコールした後、ExecuteBatch()を使用してその文をnumRows回実行します。numRowsの値はPrepareBatch()とBindParameter()コールで指定したbatSz(バッチ・サイズ)値未満である必要がありますが、アプリケーション・ロジックで必要な場合はbatSz未満であってもかまいません。
このメソッドでは、0からbatSzの範囲の値の、更新された行数を返します。(ODBCに精通している場合、これはODBCのSQLParamOptionsコールの3番目の*pirowパラメータになります。SQLParamOptionsの詳細は、ODBC APIのリファレンス・マニュアルを参照してください。)
アプリケーションでは、ExecuteBatch()をコールする前に、BindParameter()で以前にバインドしたパラメータの配列に有効な値を入力する必要があります。
(通常は一意性の制約違反が原因の)エラーが発生した場合、例外としてTTStatusオブジェクトがスローされます。このとき、戻り値は無効で、バッチは完了していないので、一般的にはロールバックを行う必要があります。
例3-5にExecuteBatch()メソッドの使用方法を示します。このメソッドの使用方法は、bulktestクイック・スタート・デモでも確認できます。(「TimesTen TTClassesデモについて」を参照してください。)
例3-5 ExecuteBatch()メソッドの使用方法
次のとおり、まず2つの列を持つ表を作成します。
CREATE TABLE batch_table (a TT_INTEGER, b VARCHAR2(100));
次にサンプル・コードを示します。サイズが50のバッチで表の行を移入します。
#define BATCH_SIZE 50
#define VARCHAR_SIZE 100
int int_array[BATCH_SIZE];
char char_array[BATCH_SIZE][VARCHAR_SIZE];
// Prepare the statement
TTCmd insert;
TTConnection connection;
// (assume a connection has been established)
try {
insert.PrepareBatch (&connection,
(const char*)"insert into batch_table values (?,?)",
BATCH_SIZE);
// Commit the prepared statement
connection.Commit();
// Bind the arrays of parameters
insert.BindParameter(1, BATCH_SIZE, int_array);
insert.BindParameter(2, BATCH_SIZE, (char **)char_array, VARCHAR_SIZE);
// Execute 5 batches, inserting a total of 5 * BATCH_SIZE rows into
// the database
for (int iter = 0; iter < 5; iter++)
{
// Populate the value arrays with values.
// (A more meaningful way of putting data into
// the database is to read values from a file, for example,
// rather than generating them arbitrarily.)
for (int i = 0; i < BATCH_SIZE; i++)
{
int_array[i] = i * iter + i;
sprintf(char_array[i], "varchar value # %d", i*iter+ i);
}
// Execute the batch insert statement,
// which inserts the entire contents of the
// integer and char arrays in one operation.
int num_ins = insert.ExecuteBatch(BATCH_SIZE);
cerr << "Inserted " << num_ins << " rows." << endl;
connection.Commit();
} // for iter
} catch (TTError er1) {
cerr << er1 << endl;
}
たとえば、列の1つに一意制約の違反がある場合などは、更新された行数(この例ではnum_ins)をBATCH_SIZEよりも少なくすることができます。例3-6のようなコード使用して、この状況を確認し、必要に応じてトランザクションをロールバックできます。
TimesTenには、表、ビュー、マテリアライズド・ビュー、順序およびシノニムなどのデータベース・オブジェクトについて、オブジェクトレベルの解決法でデータベース・アクセスを制御する機能が含まれています。アクセス制御の権限は、データベースでSQLが準備されるときと実行されるときの両方で確認され、パフォーマンス・コストの大部分は準備時に発生します。「アクセス制御に関するTimesTen機能の考慮事項」を参照してください。
例3-6 ExecuteBatch()の使用およびBATCH_SIZEの確認
for (int iter = 0; iter < 5; iter++)
{
// Populate the value arrays with values.
// (A better way of putting meaningful data into
// the database is to read values from a file,
// rather than generating them arbitrarily.)
for (int i = 0; i < BATCH_SIZE; i++)
{
int_array[i] = i * iter + i;
sprintf(char_array[i], "varchar value # %d", i*iter+i);
}
// now we execute the batch insert statement,
// which does the work of inserting the entire
// contents of the integer and char arrays in
// one operation
int num_ins = insert.ExecuteBatch(BATCH_SIZE);
cerr << "Inserted " << num_ins << " rows (expected "
<< BATCH_SIZE << " rows)." << endl;
if (num_ins == BATCH_SIZE) {
cerr << "Committing batch" << endl;
connection.Commit();
}
else {
cerr << "Some rows were not inserted as expected, rolling back "
<< "transaction." << endl;
connection.Rollback();
break; // jump out of batch insert loop
}
} // for loop
void PrepareBatch(TTConnection* cP, const char* sqlp, unsigned short batSz)
PrepareBatch()は、Prepare()の類似メソッドですが、バッチでのINSERT、UPDATEまたはDELETE文が可能です。Prepare()では、cPパラメータとsqlpパラメータを使用します。「Prepare()」を参照してください。
batSz (バッチ・サイズ)パラメータでは、ExecuteBatch()への後続のコールによって実行される挿入、更新、削除操作の最大数を指定します。
エラーが発生するとTTStatusオブジェクトが例外としてスローされます。
TimesTenには、表、ビュー、マテリアライズド・ビュー、順序およびシノニムなどのデータベース・オブジェクトについて、オブジェクトレベルの解決法でデータベース・アクセスを制御する機能が含まれています。アクセス制御の権限は、データベースでSQLが準備されるときと実行されるときの両方で確認され、パフォーマンス・コストの大部分は準備時に発生します。「アクセス制御に関するTimesTen機能の考慮事項」を参照してください。
|
注意: クライアント/サーバー接続を使用している場合に、クライアントとサーバー間の不要なラウンドトリップを回避するために、PrepareBatch()メソッドによって遅延準備と呼ばれる処理が実行され、リクエストは要求されるまでサーバーに送信されません。詳細は、『Oracle TimesTen In-Memory Database C開発者ガイド』のTimesTenの遅延準備に関する説明を参照してください。 |
(バッチ操作のバージョン)
void setParamLength(int pno, unsigned short rowno, int byteLen)
このメソッドは、ExecuteBatch()をコールする前に、バインドされたパラメータ値の長さを設定します。pno引数は、SQL文内のパラメータ番号を指定します(最初のパラメータが番号1です)。rowno引数は、バインド対象のパラメータ配列の行番号を指定します(ここで最初の行番号は1です)。byteLenパラメータでは、終わりのNULLはカウントしない希望の長さをバイト単位で指定します。NULLで終わる文字列については、byteLenのかわりにSQL_NTSを設定することも可能です。(また、次で説明するsetParamNull()バッチ・メソッドと同等の、SQL_NULL_DATAに設定することも可能です。)
|
注意:
|
(バッチ操作のバージョン)
void setParamNull(int pno, unsigned short rowno)
このメソッドでは、ExecuteBatch()のコール前に、バインドされたパラメータ値をNULLに設定します。pno引数は、SQL文内のパラメータ番号を指定します(最初のパラメータが番号1です)。rowno引数は、バインド対象のパラメータ配列の行番号を指定します(ここで最初の行番号は1です)。
|
注意:
|
これらのクラスでは、TimesTenシステム・カタログを検証できます。
TTCatalogクラスを使用すると、システム・カタログからのメタデータの読取りが容易になります。TTCatalogオブジェクトのデータが構造には、読み取られた情報が含まれます。
各TTCatalogオブジェクトの内部には、TTCatalogTableオブジェクトの配列が含まれます。各TTCatalogTableオブジェクトには、TTCatalogColumnオブジェクトの配列と、TTCatalogIndexオブジェクトの配列が含まれます。
TTCatalog内では次のODBC関数が使用されます。
SQLTables()
SQLColumns()
SQLSpecialColumns()
SQLStatistics()
この項では、次のクラスについて説明します。
TTCatalogクラスは、データベース内の表に関するメタデータ情報へのプログラム的なアクセスに使用される、トップ・レベルのクラスです。TTCatalogオブジェクトの内部には、TTCatalogTableオブジェクトの配列があります。クラス・コンストラクタを除くTTCatalogのすべてのパブリック・メソッドを使用して、そのTTCatalogTable配列への読取り専用アクセスを取得します。
TTCatalogコンストラクタは、connパラメータをキャッシュし、すべての内部データ構造を適切に初期化します。
TTCatalog (TTConnection* conn)
TTCatalogオブジェクトを使用するには、そのfetchCatalogData()メソッドをコールします(後述の説明を参照)。fetchCatalogData()メソッドは、データベース接続を使用するTTCatalogの唯一のメソッドです。その他のメソッドは、単純にfetchCatalogData()から取得したデータを返します。
| メソッド | 説明 |
|---|---|
fetchCatalogData() |
データベース内のカタログを読み取って表および索引に関する情報を取得し、この情報をTTCatalog内部データ構造に格納します。 |
getNumSysTables() |
データベース内のシステム表の数を返します。 |
getNumTables() |
データベース内の表の合計数を返します(ユーザー表とシステム表)。 |
getNumUserTables() |
データベース内のユーザー表の数を返します。 |
getTable() |
指定された表のTTCatalogTableオブジェクトへの定数参照を返します。 |
getTableIndex() |
指定された表に対するTTCatalogオブジェクト内の索引を返します。 |
getUserTable() |
(が指定された)システム内のn番目のユーザー表に対応するTTCatalogTableオブジェクトへの定数参照を返します。 |
void fetchCatalogData()
これは、データベースと通信するTTCatalogの唯一のメソッドです。データベース内のカタログを読み取って表および索引に関する情報を取得し、それをTTCatalog内部データ構造に格納します。
その後、構築されたTTCatalogオブジェクトは完全にオフラインで使用されます。データベースにはもう接続されていません。
TTCatalogアクセッサ・メソッドのいずれかを使用する前に、このメソッドをコールする必要があります。
次の例に、TTCatalogの使用方法を示します。
例3-7 カタログ・データのフェッチ
TTConnection conn;
conn.Connect(DSN=TptbmData37);
TTCatalog cat (&conn);
cat.fetchCatalogData();
// TTCatalog cat is no longer connected to the database;
// you can now query it through its read-only methods.
cerr << "There are " << cat.getNumTables() << " tables in this database:" << endl;
for (int i=0; i < cat.getNumTables(); i++)
cerr << cat.getTable(i).getTableOwner() << "."
<< cat.getTable(i).getTableName() << endl;
int getNumSysTables()
データベース内のシステム表の数を返します。後述のメソッドgetNumTables()およびgetNumUserTables()も参照してください。
int getNumTables()
データベース内の表の合計数を返します(ユーザー表とシステム表)。前述のメソッドgetNumSysTables()と、後述のメソッドgetNumUserTables()も参照してください。
int getNumUserTables()
データベース内のユーザー表の数を返します。前述のメソッドgetNumSysTables()と、後述のメソッドgetNumTables()も参照してください。
const TTCatalogTable& getTable(const char* owner, const char* tblname) const TTCatalogTable& getTable(int tno)
指定された表のTTCatalogTableオブジェクトへの定数参照を返します。「getUserTable()」も参照してください。
最初のシグネチャは、tblnameという名前のownerによって所有される表に使用されます。
2番目のシグネチャは、システム内の表番号tnoに対応する表に使用されます。これは、システム内のすべての表に対する反復処理を容易にするためのものです。この配列内の表の順番は任意です。
次の関係が成立しています。
0 <= tno < getNumTables()
「TTCatalogTable」も参照してください。
int getTableIndex(const char* owner, const char* tblname) const
このメソッドは、指定されたowner.tblnameオブジェクトに対するTTCatalogオブジェクト内の索引をフェッチします。owner.tblnameが存在しない場合は-2を返します。fetchCatalogData()が最初にコールされない場合-1を返します。
例3-8では、TTCatalogオブジェクトのTTUSER.MYDATA表に関する情報を取得します。次で説明するTTCatalogTableのメソッドをコールして、この表に関する情報を取得することができます。
const TTCatalogTable& getUserTable(int tno)
システム内のユーザー表番号tnoと対応するTTCatalogTableオブジェクトに対する定数参照を返します。このメソッドは、システム内のすべてのユーザー表に対する反復処理を容易にするためのものです。この配列のユーザー表の順番は任意です。「getTable()」も参照してください。
次の関係が成立しています。
0 <= tno < getNumUserTables()
|
注意: システム表には同等のメソッドはありません。 |
TTCatalogTableオブジェクトはTTCatalog::getTable()メソッドを使用して取得され、表の列および索引に関するメタデータ情報がすべて格納されます。
| メソッド | 説明 |
|---|---|
getColumn() |
表の番目の列に対応するTTCatalogColumnへの定数参照を返します。 |
getIndex() |
(が指定された)表内のn番目の索引に対応するTTCatalogIndexオブジェクトへの定数参照を返します。 |
getNumColumns() |
表の列数を返します。 |
getNumIndexes() |
表の索引数を返します。 |
getNumSpecialColumns() |
この表の特殊列の数を返します。「TTCatalogSpecialColumn」を参照してください。 |
getSpecialColumn() |
この表から、指定した列番号に従った特殊列(TTCatalogSpecialColumnオブジェクト)を返します。 |
getTableName() |
表の名前を返します。 |
getTableOwner() |
表の所有者を返します。 |
getTableType() |
ODBC SQLTables関数より返される表タイプを返します。 |
isSystemTable() |
表がシステム表の場合はTRUEを返します。 |
isUserTable() |
表がユーザー表の場合はTRUEを返します。 |
const TTCatalogColumn& getColumn(int cno)
表の列番号cnoと対応するTTCatalogColumnオブジェクトに対する定数参照を返します。このメソッドは、表のすべての列に対する反復処理を容易にするためのものです。
次の関係が成立しています。
0 <= cno < getNumColumns()
const TTCatalogIndex& getIndex(int num)
表の索引番号numと対応するTTCatalogIndexオブジェクトに対する定数参照を返します。このメソッドは、表のすべての索引に対する反復処理を容易にするためのものです。この配列の表の索引の順番は任意です。
次の関係が成立しています。
0 <= num < getNumIndexes()
int getNumSpecialColumns()
このTTCatalogTableオブジェクト内の特殊列の数を返します。TimesTenでサポートされる特殊列はROWIDのみのため、常に1が返されます。
「TTCatalogSpecialColumn」も参照してください。
const TTCatalogSpecialColumn& getSpecialColumn(int num) const
このTTCatalogTableオブジェクトから、指定した列番号に従い特殊列(TTCatalogSpecialColumnオブジェクト)を返します。TimesTenでは、これはROWID疑似列のみになります。
「TTCatalogSpecialColumn」も参照してください。
const char* getTableType() const
ODBC SQLTablesコールからとして、このTTCatalogTableオブジェクトの表タイプを返します。これは、TimesTenでは、TABLE、SYSTEM TABLE、VIEWまたはSYNONYMになります。
bool isSystemTable()
表がシステム表(SYS、TTREPまたはGRIDの所有)の場合TRUEを返し、それ以外の場合はFALSEを返します。
システム表とユーザー表を区別するために、表をフィルタしたり注釈を付けることが可能な、isSystemTable()メソッドとisUserTable()メソッド(次で説明)は、TTCatalog::fetchCatalogData()へのコール後、すべての表を反復するアプリケーションに便利です。TTClassesのデモ・プログラムであるcatalogには、これの実行例があります。(「TimesTen TTClassesデモについて」を参照してください。)
TTCatalogColumnクラスは、表の1つの行のすべてのメタデータ情報を格納するために使用されます。この表はTTCatalogTableオブジェクトで表現され、このオブジェクトからTTCatalogTable::getColumn()コールを使用して列が取得されています。
| メソッド | 説明 |
|---|---|
getColumnName() |
列の名前を返します。 |
getDataType() |
列のODBC SQLデータ型を表す整数を返します。 |
getLength() |
列の長さをバイト単位で返します。 |
getNullable() |
列にNULL値を含めることができるかどうかを示します。(次の説明のとおり、これはブール値ではありません)。 |
getPrecision() |
列の精度を返します。 |
getRadix() |
列の基数を返します。 |
getScale() |
列のスケールを返します。 |
getTypeName() |
getDataType()によって返された型のTimesTen名を返します。 |
int getNullable()
列にNULL値を含めることができるかどうかを示します。SQL_NO_NULLS、SQL_NULLABLEまたはSQL_NULLABLE_UNKNOWNが返されます。
TTCatalogIndexクラスは、表の索引のメタデータ情報を保存するために使用されます。この表は、TTCatalogTableオブジェクトで表現され、このオブジェクトからTTCatalogTable::getIndex()コールを使用して索引が取得されています。
| メソッド | 説明 |
|---|---|
getCollation() |
索引の指定された列の照合を返します。 |
getColumnName() |
索引の指定された列名を返します。 |
getIndexName() |
索引の名前を返します。 |
getIndexOwner() |
索引の所有者を返します。 |
getNumColumns() |
索引の列数を返します。 |
getTableName() |
索引が作成された表の名前を返します。 |
getType() |
索引の型を返します。 |
isUnique() |
索引が一意索引かどうかを表します。 |
const char* getTableName()
索引が作成された表の名前を返します。この表は、TTCatalogTableオブジェクトで表現され、このオブジェクトからTTCatalogTable::getIndex()コールを使用して索引が取得されています。
int getType()
索引の型を返します。TimesTenでは、許容値はPRIMARY_KEY、HASH_INDEX(PRIMARY_KEYと同じ)およびRANGE_INDEXです。
このクラスは、TTCatalogTableオブジェクトとして表されるODBC SQLSpecialColumns関数コールからの結果のラッパーです。TimesTenで唯一サポートされる特殊列は、ROWID疑似列なので、TTCatalogSpecialColumnオブジェクトにはROWIDの情報しか含めることができません。
| メソッド | 説明 |
|---|---|
getColumnName() |
特殊列の名前を返します。 |
getDataType() |
特殊列のデータ型を整数で返します。 |
getLength() |
特殊列内のデータの長さをバイト単位で返します。 |
getPrecision() |
特殊列の精度を返します。 |
getScale() |
特殊列のスケールを返します。 |
getTypeName() |
特殊列のデータ型を文字列で返します。 |
TTClassesは、TimesTenのトランザクション・ログAPI(XLA)で使用するアプリケーション用の一連のクラスを備えています。
XLAはコール可能なC関数のセットであり、アプリケーションはこれで1つ以上のデータベース表の変更を監視できます。監視対象の表が別のアプリケーションによって変更されるたびに、XLAを使用しているアプリケーションにその変更が通知されます。XLAの詳細は、『Oracle TimesTen In-Memory Database C開発者ガイド』のXLAおよびTimesTenのイベント管理に関する説明を参照してください。
XLAクラスでは、TimesTenでサポートされている列の最大数と同じ数のXLA列をサポートしています。詳細は、『Oracle TimesTen In-Memory Databaseリファレンス』のシステム制限に関する説明を参照してください。
この項では、次のクラスについて説明します。
データベースへのXLA接続を作成するには、TTXlaPersistConnectionを使用します。
XLAアプリケーションでは、必要に応じて複数のTTXlaPersistConnectionオブジェクトを作成できます。各TTXlaPersistConnectionオブジェクトには、接続時に指定する、ackUpdates()メソッドとdeleteBookmarkAndDisconnect()メソッドで維持する独自のブックマークと関連付ける必要があります。多くのアプリケーションでは、XLAブックマークは1つまたは2つのみ必要です。
XLA接続の確立後、アプリケーションは、その終了までfetchUpdatesWait()メソッドを繰り返しコールするループに入ります。このループでは、トランザクション・ログで使用可能なディスク領域が一杯にならないように、できるだけ速くXLAから更新をフェッチする必要があります。
|
注意:
|
アプリケーションは、更新のバッチを処理した後、それらの更新を確認するためにackUpdates()をコールし、次のfetchUpdatesWait()のコールに備えます。更新のバッチは、setBookmarkIndex()およびgetBookmarkIndex()メソッドを使用して再生できます。また、XLAアプリケーションがfetchUpdatesWait()の後(ただしackUpdates()の前)に切断されると、fetchUpdatesWait()をコールする次の接続(同じブックマーク名を使用)は、同じ更新のバッチを参照します。
データベースからTTXlaPersistConnectionオブジェクトを切断している間に発生する更新は、失われません。これらは、別のTTXlaPersistConnectionオブジェクトが同じブックマーク名で接続されるまでトランザクション・ログに格納されます。
データベースに接続する権限は、CREATE SESSION権限を使用して、直接またはPUBLICロールを介してユーザーに付与する必要があります。「接続のアクセス制御」を参照してください。これに加え、XLA接続と機能にはXLA権限が必要です。
| メソッド | 説明 |
|---|---|
ackUpdates() |
ブックマークを次の更新セットに進めます。 |
Connect() |
指定されたブックマークで接続するか、(メソッド・シグネチャに応じ)存在しない場合は作成します。 |
deleteBookmarkAndDisconnect() |
ブックマークを削除し、データベースから切断します。 |
Disconnect() |
ブックマークはそのままにし、データベースとのXLA接続を閉じます。 |
fetchUpdatesWait() |
指定された待機時間内にトランザクション・ログの更新をフェッチします。 |
getBookmarkIndex() |
現在のトランザクション・ログの位置を取得します。 |
setBookmarkIndex() |
getBookmarkIndex()コールによって取得されたトランザクション・ログの位置を返します。 |
void ackUpdates()
このメソッドは、ブックマークを次の更新セットに進めるために使用されます。更新セットを確認した後、このブックマークからは更新は再度表示できません。したがって、setBookmarkIndex()コールではackUpdates()へのコールによって認識されたXLAレコードの再生は許可しません。(更新セットの再生については、「getBookmarkIndex()」と「setBookmarkIndex()」の説明を参照してください。)
アプリケーションは、XLAレコードのバッチが読み取られて処理されたら、利用可能なディスク領域をトランザクション・ログが一杯にしないように、更新を確認する必要がありますが、相対的に負荷の高い操作なのでackUpdates()は頻繁にコールしないようにする必要があります。
アプリケーションがレコードのバッチを読み取るためにXLAを使用し、ackUpdates()のコール前に失敗する場合、アプリケーションがXLA接続を再構築するときにレコードは取得されます。
|
注意: トランザクション・ログは、指定している場合、TimesTenLogDir属性で設定したファイル・システムの場所にあり、LogDirを指定していない場合はDataStore属性で設定した場所にあります。『Oracle TimesTen In-Memory Databaseリファレンス』のデータ・ストア属性に関する説明を参照してください。 |
virtual void Connect(const char* connStr, const char* bookmarkStr, bool createBookmarkFlag) virtual void Connect(const char* connStr, const char* username, const char* password, const char* bookmarkStr, bool createBookmarkFlag) virtual void Connect(const char* connStr, TTConnection::DRIVER_COMPLETION_ENUM driverCompletion, const char* bookmarkStr, bool createBookmarkFlag) virtual void Connect(const char* connStr, const char* bookmarkStr) virtual void Connect(const char* connStr, const char* username, const char* password, const char* bookmarkStr) virtual void Connect(const char* connStr, TTConnection::DRIVER_COMPLETION_ENUM driverCompletion, const char* bookmarkStr)
各XLA接続にはブックマーク名が関連付けられているため、切断および再接続後、トランザクション・ログ内の同じ場所が検出可能です。接続のブックマーク名はbookmarkStrパラメータで指定します。
前述の1番目のメソッドのセットのcreateBookmarkFlagブール・パラメータは、ブックマークが新規か、以前に作成されたかを示します。ブックマークを新規と指定し(createBookmarkFlag==true)、すでに存在している場合はエラーが返されます。同様に、ブックマークがすでに存在していると指定し(createBookmarkFlag==false)、存在していなかった場合はエラーが返されます。
示している2番目のメソッドのセットについて、createBookmarkFlagがない場合、TTClassesはまず提供されたブックマークを再利用して接続を試行します(createBookmarkFlag==falseと同等な動作)。そのブックマークが存在しない場合、TTClassesは次にbookmarkStrという名前の新規ブックマークの作成を試行します(createBookmarkFlag==trueと同じ動作)。このメソッドは、XLAブックマークが存在するかどうかを開発者が気にかけたくない場合に備えて、XLA接続ロジックを簡略化するために便宜上提供されているものです。
createBookmarkFlagの有無にかかわらずいずれのモードのときも、接続文字列または別のパラメータを使用してユーザー名とパスワードを指定するか、DRIVER_COMPLETION_ENUM値を指定します。DRIVER_COMPLETION_ENUMの詳細は、「TTConnection」を参照してください。
データベースに接続する権限は、CREATE SESSION権限を使用して、直接またはPUBLICロールを介してユーザーに付与する必要があります。「接続のアクセス制御」を参照してください。これに加え、XLA接続を作成するにはXLA権限が必要です。
|
注意: 特定のブックマーク名で接続できるXLA接続は1つのみです。複数の接続が同じブックマークに接続しようとすると、エラーが返されます。 |
void deleteBookmarkAndDisconnect()
このメソッドでは、データベースがそのブックマークのレコードをそれ以上保持しないように接続と現在関連付けられているブックマークをまず削除し、その後データベースから切断します。
ブックマークを削除せずに切断するには、かわりにDisconnect()メソッドを使用します。
virtual void Disconnect()
このメソッドは、データベースとのXLA接続を閉じます。このメソッドをコールした後も、XLAブックマークは存続します。
ブックマークを削除してデータベースから切断する場合は、かわりにdeleteBookmarkAndDisconnect()を使用します。
void fetchUpdatesWait(ttXlaUpdateDesc_t*** arry, int maxrecs, int* recsP, int seconds)
このメソッドは、データベースの変更を記述したレコードのセットをフェッチするために使用します。ttXlaUpdateDesc_t構造体のリストが返されます。フェッチされるXLA更新がない場合、このメソッドは指定された秒数待機してから返されます。
待機する秒数をsecondsで指定し、受信するレコードの最大数をmaxrecsで指定します。このメソッドは、実際に受信したレコードの数recsPと変更を定義する構造をポイントするポインタの配列arryを返します。
このメソッドによって返されるttXlaUpdateDesc_t構造体は、XLA仕様で定義されます。これらのメソッドのC++オブジェクト指向カプセル化は提供されません。通常、fetchUpdatesWait()のコール後、アプリケーションはTTXlaTableList::HandleChange()へのコールのシーケンスでこれらのttXlaUpdateDesc_t構造を処理します。
データ構造の詳細は、『Oracle TimesTen In-Memory Database C開発者ガイド』のttXlaUpdateDesc_tに関する説明を参照してください。
void getBookmarkIndex()
このメソッドは、現在のブックマーク位置を取得し、以降のsetBookmarkIndex()コールで使用可能となるクラスのプライベート・データ・メンバーに保存します。
void setBookmarkIndex()
このメソッドでは、保存されたトランザクション・ログの索引に戻り、ブックマークを以前getBookmarkIndex()へのコールで取得したアドレスにリストアします。このメソッドを使用すると、XLAレコードのバッチを再生できます。
ackUpdates()がコールされると、格納されているトランザクション・ログ・プレースホルダが無効になることに注意してください。ackUpdates()の後でsetBookmarkIndex()がコールされても、以前に取得されたブックマークの位置まで戻ることができないため、エラーが返されます。
変更通知レコードからの行イメージを表すTTXlaRowViewerを使用すると、XLA変更通知レコードの構造と新旧の列値を検証することができます。
このクラスのメソッドは、変更通知レコード内の行イメージから列値を検証するために使用できます。TTXlaTableクラス(「TTXlaTable」)の関連情報も参照してください。
行を検証する前に、TTXlaRowViewerオブジェクトはTTXlaTableHandler::HandleInsert()、HandleUpdate()またはHandleDelete()メソッド、またはユーザー記述のオーバーロード・メソッド内で起動されるsetTuple()メソッドを使用する行と関連付ける必要があります。isNull()メソッドを使用すると、列にnull値があるかを確認できます。nullではない列値は適切なオーバーロードされるGet()メソッドを使用して検査できます。
| メソッド | 説明 |
|---|---|
columnPrec() |
行イメージの指定した列の精度を返します。 |
columnScale() |
行イメージの指定した列のスケールを返します。 |
Get() |
行イメージ内の指定した列の値をフェッチします。 |
getColumn() |
行イメージから指定した列を返します。 |
isColumnTTTimestamp() |
行イメージ内の指定した列がTT_TIMESTAMP列であるかどうかを示します。 |
isNull() |
行イメージ内の指定した列にNULL値があるかどうかを示します。 |
numUpdatedCols() |
行イメージ内で更新した列数を返します。 |
setTuple() |
TTXlaRowViewerオブジェクトを指定された行イメージに関連付けます。 |
updatedCol() |
通常は、すべての更新済列に対する反復処理中に、更新された列の行イメージ内での列番号を返します。 |
void Get(int cno, TYPE* valueP) void Get(int cno, TYPE* valueP, int* byteLenP)
行イメージ内の列番号cno値を取得します。これらのメソッドは、TTCmd::getColumn()メソッドによく似ています。
次の表3-5では、サポートされるSQLデータ型および各データ型での使用に適したGet()バージョンを示します。格納されるデータ型の種類に従って、アプリケーションを設計します。たとえば、データ型NUMBER(9,0)には、Get(int、int*)メソッドを使用すると、データを損失することなくアクセスできます。
表3-5 サポートされる表の列型のGet()バージョン
| XLAデータ型 | データベース・データ型 | Get() variant |
|---|---|---|
|
|
|
Get(cno, char** cPP) |
|
|
|
Get(cno, SQLWCHAR** wcPP, byteLenP) |
|
|
|
Get(cno, char** cPP) |
|
|
|
Get(cno, SQLWCHAR** wcPP, byteLenP) |
|
|
|
Get(cno, SQLTINYINT* iP) |
|
|
|
Get(cno, short* iP) |
|
|
|
Get(cno, int* iP) |
|
|
|
Get(cno, SQLBIGINT* biP) |
|
|
|
Get(cno, float* fP) |
|
|
|
Get(cno, double* dP) |
|
|
|
Get(cno, char** cPP) |
|
|
|
Get(cno, TIME_STRUCT* tP) |
|
|
|
Get(cno, DATE_STRUCT* dP) |
|
|
|
Get(cno, TIMESTAMP_STRUCT* tsP) |
|
|
|
Get(cno, const void** binPP, byteLenP) |
|
|
|
Get(cno, const void** binPP, byteLenP) |
|
|
|
Get(cno, double* dP) Get(cno, char** cPP) Get(cno, short* iP) Get(cno, int* iP) Get(cno, SQLBIGINT* biP) |
|
|
|
Get(cno, TIMESTAMP_STRUCT* tsP) |
|
|
|
Get(cno, TIMESTAMP_STRUCT* tsP) |
|
|
|
Get(cno, char** cPP) |
|
|
|
Get(cno, SQLWCHAR** wcPP, byteLenP) |
|
|
|
Get(cno, char** cPP) |
|
|
|
Get(cno, SQLWCHAR** wcPP, byteLenP) |
|
|
|
Get(cno, double* dP) Get(cno, char** cPP) |
|
|
|
Get(cno, const void** binPP, byteLenP) |
|
|
|
Get(cno, char** cPP) |
|
|
|
Get(cno, SQLWCHAR** wcPP, byteLenP) |
const TTXlaColumn* getColumn(u_int cno) const
TTXlaColumnオブジェクトを、行イメージ内の列番号cnoのメタデータとともに返します。
bool isColumnTTTimestamp(int cno)
行イメージの列番号cnoがTT_TIMESTAMP列の場合は、TRUEを返し、それ以外の場合はFALSEを返します。
void setTuple(ttXlaUpdateDesc_t* updateDescP, int whichTuple)
行を検証する前に、このメソッドをまずコールして、特定の行イメージとTTXlaRowViewerオブジェクトを関連付ける必要があります。これはTTXlaTableHandler::HandleInsert()、HandleUpdate()またはHandleDelete()メソッド内で起動されるか、ユーザー記述のオーバーロードされたメソッドによって起動されます。これは、通常、TTXlaTableHandler::HandleChange()メソッドをオーバーロードする際に、コールします。これの使用例は、クイック・スタートのxlasubscriber1のデモのとおりです。(「TimesTen TTClassesデモについて」を参照してください。)
TTXlaPersistConnection::fetchUpdatesWait()によって返されるttXlaUpdateDesc_t構造体に含まれる行の数は、0(ゼロ)、1または2です。次のことに注意してください。
表に挿入された行を定義する構造体には、挿入された行の行イメージが含まれます。
表から削除された行を定義する構造体には、削除された行の行イメージが含まれます。
表内で更新された行を定義する構造体には、更新前の行イメージと更新後の行イメージが含まれます。
表またはデータベースの他の変更を定義する構造体には、行イメージが含まれません。たとえば、索引が削除されたことをレポートする構造体には行イメージが含まれません。
setTuple()メソッドは2つの引数を受け入れます。
データベース変更を定義する特定のttXlaUpdateDesc_t構造体へのポインタ
更新構造体内のどのタイプの行イメージを調べるかを指定する整数。
有効な値は、次のとおりです。
INSERTED_TUP: 新しく挿入された行を調べます。
DELETED_TUP: 削除された行を調べます。
UPDATE_OLD_TUP: 更新前の行を調べます。
UPDATE_NEW_TUP: 更新後の行を調べます。
SQLUSMALLINT updatedCol(u_int cno)
更新された列の列番号を返します。入力パラメータには、1からnを繰り返すことができます(ここで、nはnumUpdatedCols()から返される数字です)。例3-9に、更新された各行を取得するためにupdatedCol()とnumUpdatedCols()を使用する、TimesTenのクイック・スタート・デモのxlasubscriber1のスニペットを示します。(「TimesTen TTClassesデモについて」を参照してください。)
表3-9 TTXlaRowViewer::numUpdatedCols()とupdatedCol()の使用
void
SampleHandler::HandleUpdate(ttXlaUpdateDesc_t* )
{
cerr << row2.numUpdatedCols() << " column(s) updated: ";
for ( int i = 1; i <= row2.numUpdatedCols(); i++ )
{
cerr << row2.updatedCol(i) << "("
<< row2.getColumn(row2.updatedCol(i)-1)->getColName() << ") ";
}
cerr << endl;
}
TTXlaTableHandlerクラスは、表の変更追跡を有効および無効にするメソッドを提供します。また、XLAからの更新通知レコードを処理するメソッドも提供します。これは、アプリケーション開発者が特定の表の変更を処理するカスタマイズ済クラスを記述する際の基本クラスです。
コンストラクタは、TTXlaTableHandlerオブジェクトを特定の表に関連付け、TTXlaTableHandlerオブジェクトに含まれるTTXlaTableデータ・メンバーを初期化します。
TTXlaTableHandler(TTXlaPersistConnection& conn, const char* ownerP, const char* nameP)
「TTXlaTable」も参照してください。
アプリケーション開発者は、TTXlaTableHandlerから1つ以上のクラスを導出し、そのクラスのHandleInsert()、HandleDelete()およびHandleUpdate()メソッドに、アプリケーションのロジックの大部分を配置できます。
表ごとにTTXlaTableHandlerから複数のクラスを導出する設計を行うことも可能です。たとえば、顧客データの変更を処理するビジネス・ロジックなどをCustomerTableHandlerクラスに実装し、注文データの変更を処理するビジネス・ロジックをOrderTableHandlerクラスに実装します。
もう1つの可能な設計は、様々な使用例を処理する1つ以上の汎用クラスをTTXlaTableHandlerから導出することです。たとえば、TTXlaTableHandlerから導出した汎用クラスを使用して、公開/サブスクライブ・システムを介して変更をパブリッシュできます。
TTXlaTableHandlerの拡張クラスの例は、TimesTenのクイック・スタートのxlasubscriber1とxlasubscriber2のデモを参照してください。(「TimesTen TTClassesデモについて」を参照してください。)
| メンバー | 説明 |
|---|---|
TTXlaTable tbl |
これは処理対象の表に関連付けられたメタデータ用です。 |
TTXlaRowViewer row |
これは、ユーザーが記述したHandleInsert()、HandleDelete()およびHandleUpdate()メソッド内の挿入または削除対象の行、更新対象の行の古いイメージを参照するために使用します。 |
TTXlaRowViewer row2 |
これは、ユーザーによって記述されたHandleUpdate()メソッド内の更新対象行の新しいイメージを参照するために使用します。 |
| メソッド | 説明 |
|---|---|
DisableTracking() |
表のXLA更新追跡を無効にします。 |
EnableTracking() |
表のXLA更新追跡を有効にします。 |
generateSQL() |
特定のXLAレコードに関連付けられたSQLを返します。 |
HandleChange() |
ttXlaUpdateDesc_tからレコードを適切な処理ルーチンにディスパッチして処理します。 |
HandleDelete() |
削除操作を処理する際、HandleChange()メソッドのコール時にこれは起動されます。 |
HandleInsert() |
これは、挿入操作を処理する際にHandleChange()メソッドがコールされるとき、起動されます。 |
HandleUpdate() |
これは、更新操作を処理する際にHandleChange()メソッドがコールされるとき、起動されます。 |
virtual void DisableTracking()
表のXLA更新追跡を無効にします。このメソッドがコールされると、XLAブックマークでは、それ以降表に対する変更の情報を取得しなくなります。
virtual void EnableTracking()
表のXLA更新追跡を有効にします。このメソッドがコールされるまで、XLAブックマークでは、表に対する変更の情報を取得しません。
void generateSQL (ttXlaUpdateDesc_t* updateDescP, char* buffer, SQLINTEGER maxByteLen, SQLINTEGER* actualByteLenP)
このメソッドでは、特定のXLAレコードに関連付けられたSQLを出力します。SQL文字列は、bufferパラメータを介して返されます。バッファに領域を割り当て、最大長をmaxByteLenで指定します。actualByteLenPパラメータは、返されたSQL文字列の実際の長さの情報を返します。
maxByteLenが生成されたSQL文字列の長さよりも短い場合、TTStatusエラーがスローされ、bufferおよびactualByteLenPの内容は変更されません。
virtual void HandleChange(ttXlaUpdateDesc_t* updateDescP) virtual void HandleChange(ttXlaUpdateDesc_t* updateDescP, void* pData)
ttXlaUpdateDesc_tオブジェクトを適切な処理ルーチンにディスパッチして処理します。更新記述が分析され、それが削除、挿入または更新操作のいずれであるかが判別されます。その後、適切な処理メソッド(HandleDelete()、HandleInsert()またはHandleUpdate())がコールされます。
TTXlaTableHandlerから継承されるクラスでは、TTXlaTableHandler::HandleChange()メソッドをオーバーロードする際にオプションでpDataパラメータを使用できます。このオプションのパラメータは、処理されたばかりのXLAレコードのバッチがトランザクションの範囲内で終了したか判断するのに便利です。これを把握していると、アプリケーションでTTConnection::ackUpdates()を起動する適切なタイミングを判断できます。pDataパラメータの使用例は、「トランザクション境界におけるXLA更新の確認」を参照してください。
TTXlaTableListオブジェクトの詳細は、「HandleChange()」を参照してください。
virtual void HandleDelete(ttXlaUpdateDesc_t* updateDescP) = 0
このメソッドは、削除操作を処理するためにHandleChange()メソッドがコールされるたびに起動されます。
HandleDelete()はTTXlaTableHandler基本クラスには実装されていません。それを導出したクラスから、削除した行を処理する適切なロジックとともに実装する必要があります。
表から削除された行は、型TTXlaRowViewerのrow保護メンバーを介して利用できます。
virtual void HandleInsert(ttXlaUpdateDesc_t* updateDescP) = 0
このメソッドは、挿入操作を処理するためにHandleChange()メソッドがコールされるたびに起動されます。
HandleInsert()はTTXlaTableHandler基本クラスには実装されていません。それを導出したクラスから、挿入した行を処理する適切なロジックとともに実装する必要があります。
表に挿入された行は、型TTXlaRowViewerのrow保護メンバーを介して利用できます。
virtual void HandleUpdate(ttXlaUpdateDesc_t* updateDescP) = 0
このメソッドは、更新操作を処理するためにHandleChange()メソッドがコールされるたびに起動されます。
HandleUpdate()はTTXlaTableHandler基本クラスには実装されていません。それを導出したクラスから、更新した行を処理する適切なロジックとともに実装する必要があります。
表から更新された行の以前のバージョンは、型TTXlaRowViewerのrow保護メンバーを介して利用できます。行の新しいバージョンは、こちらも型はTTXlaRowViewerであるrow2保護メンバーを介して利用できます。
TTXlaTableListクラスには、一連のTTXlaTableHandlerオブジェクトがあり、更新通知イベントを適切なTTXlaTableHandlerにディスパッチするために使用されます。更新通知をXLAから受信すると、適切なTTXlaTableHandlerオブジェクトの適切なHandleXxx()メソッドをコールし、レコードは処理されます。
たとえば、CustomerTableHandler型のオブジェクトが表CUSTOMERの変更を処理し、OrderTableHandler型のオブジェクトが表ORDERSの変更を処理する場合、アプリケーションでは両方のオブジェクトをTTXlaTableListオブジェクト内に持つ必要があります。XLA更新通知レコードがXLAからフェッチされたとき、TTXlaTableList::HandleChange()をコールすることによって、それらのレコードを適切なハンドラにディスパッチできます。
コンストラクタには2種類の形式があります。
TTXlaTableList(TTXlaPersistConnection* cP, unsigned int num_tbls_to_monitor)
ここでnum_tbls_to_monitorは、監視するデータベース・オブジェクトの数です。
または
TTXlaTableList(TTXlaPersistConnection* cP);
cPは、XLA操作に使用するデータベース接続を示します。この形式のコンストラクタでは、最大150のデータベース・オブジェクトを監視できます。
TTXlaTableHandlerオブジェクトをTTXlaTableHandlerオブジェクトに登録すると、XLAから更新通知レコードをフェッチし、適切なメソッドにディスパッチして処理するプロセスをループによって実行できます。
| メソッド | 説明 |
|---|---|
add() |
リストにTTXlaTableHandlerオブジェクトを追加します。 |
del() |
リストからTTXlaTableHandlerオブジェクトを削除します。 |
HandleChange() |
ttXlaUpdateDesc_t構造から取得されたレコードを処理します。 |
void HandleChange(ttXlaUpdateDesc_t* updateDescP) void HandleChange(ttXlaUpdateDesc_t* updateDescP, void* pData)
XLAからttXlaUpdateDesc_tオブジェクトを受け取った場合、レコードがどの表を参照するか判断し、適切なTTXlaTableHandlerオブジェクトのHandleChange()をコールする、このメソッドをコールして処理できます。
pDataパラメータの説明を含むTTXlaTableHandlerオブジェクトの詳細は、「HandleChange()」を参照してください。
TTXlaTableクラスは、変更の監視対象の表のメタデータをカプセル化します。これは、TimesTen ttXlaTblDesc_t Cデータ構造のメタデータ・インタフェースとして動作します。(『Oracle TimesTen In-Memory Database C開発者ガイド』のttXlaTblDesc_tに関する説明を参照。)
ユーザー・アプリケーションでTTXlaTableHandlerを拡張するクラスが作成される場合、通常、列名をそのXLA列番号とマップするためにTTXlaTable::getColNumber()がコールされます。この列番号は、その後TTXlaRowViewer::Get()メソッドへの入力に使用できます。これは、TimesTenのクイック・スタートのxlasubscriber2のデモで示されています。(「TimesTen TTClassesデモについて」を参照してください。)
このクラスには、表の名前、所有者、列数を返す便利なメタデータ関数もあります。
| メソッド | 説明 |
|---|---|
getColNumber() |
表の指定した列の列番号を返します。 |
getNCols() |
表の列数を返します。 |
getOwnerName() |
表の所有者名を返します。 |
getTableName() |
表の名前を返します。 |
int getColNumber(const char* colNameP) const
表の列名を指定した場合、このメソッドでは列番号を返すか、その名前の列がない場合は-1を返します。
TTXlaColumnオブジェクトには、変更の監視対象の表の単一行のメタデータが含まれます。これは、TimesTen ttXlaColDesc_t Cデータ構造のメタデータ・インタフェースとして動作します。(『Oracle TimesTen In-Memory Database C開発者ガイド』のttXlaColDesc_tに関する説明を参照してください。)列名、型、精度、スケールを含む情報を取得できます。
| メソッド | 説明 |
|---|---|
getColName() |
列の名前を返します。 |
getPrecision() |
列の精度を返します。 |
getScale() |
列のスケールを返します。 |
getSize() |
列データのサイズをバイト単位で返します。 |
getSysColNum() |
データベースに保存されているシステム生成のこの行の列番号を返します。 |
getType() |
列のデータ型を整数で返します。 |
getUserColNum() |
ユーザーがオプションで指定した列番号を返すか、0を返します。 |
isNullable() |
列でNULL値が許可されるかどうかを示します。 |
isPKColumn() |
列が表の主キーであるか示します。 |
isTTTimestamp() |
列がTT_TIMESTAMP列であるか示します。 |
isUpdated() |
列が更新されたかどうかを示します。 |
SQLUINTEGER getSysColNum() const
これは、1から開始されるシステム生成の列の列番号です。これは、SYS.COLUMNSの対応するCOLNUM値と同じです。(『Oracle TimesTen In-Memory Databaseシステム表およびビュー・リファレンス』のSYS.COLUMNSに関する説明を参照してください。)
int getType() const
列のTimesTen XLAデータ型(TTXLA_xxx)を表す整数を返します。これはTimesTen ttXlaColDesc_tデータ構造のdataTypeフィールドからの値です。場合によっては、これはODBC SQLデータ型(SQL_xxx)と対応する標準の整数値と対応します。
TimesTenのXLAのデータ型の詳細は、『Oracle TimesTen In-Memory Database C開発者ガイド』のXLAのデータ型に関する説明を参照してください。対応する整数値は、TTXla.hヘッダー・ファイルを含む任意のTTClassesアプリケーションで使用されるために定義されています。
データ構造の詳細は、『Oracle TimesTen In-Memory Database C開発者ガイド』のttXlaColDesc_tに関する説明を参照してください。
SQLUINTEGER getUserColNum() const
ユーザーがオプションでttSetUserColumnIDのTimesTen組込みプロシージャで指定した列番号を返すか、0を返します。
『Oracle TimesTen In-Memory Databaseリファレンス』のttSetUserColumnIDに関する説明を参照してください。
