このリファレンスの章では、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 を拡張する場合、コール・シーケンスに driverCompletionがある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が指定された)システム内の 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() |
表の i番目の列に対応するTTCatalogColumn への定数参照を返します。 |
getIndex() |
( nが指定された)表内の 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
オブジェクトの適切なHandle
Xxx()
メソッドをコールし、レコードは処理されます。
たとえば、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に関する説明を参照してください。