4 クラスの説明

この章では、TTClassesへの外部インタフェースにおけるすべてのクラスについて説明します。 また、一部の内部TTClassesの概要についても説明します。この章の内容は次のとおりです。

• 一般的に使用されるTTClasses

• システム・カタログ・クラス

• XLAクラス

• 内部クラス

一般的に使用されるTTClasses

この項では、次のクラスについて説明します。

• TTStatus

• TTConnection

• TTCmd

• TTConnectionPool

• TTGlobal

TTStatus

TTStatusクラスは、TTClassesコレクション内の他のクラスで、エラーおよび警告の例外を捕捉するために使用されます。 TTStatusは、ODBC関数SQLErrorの付加価値C++ラッパーとみなすことができます。

サブクラス

TTStatusには、次のサブクラスがあります。

• TTError

• TTWarning

TTError

TTErrorはTTStatusのサブクラスであり、ODBCエラー（リターン・コード: SQL_ERROR、SQL_INVALID_HANDLE）をカプセル化するために使用されます。

TTWarning

TTWarning はTTStatusのサブクラスであり、ODBC警告（リターン・コード: SQL_SUCCESS_WITH_INFO）をカプセル化するために使用されます。

通常、ODBC警告はODBCエラーほど深刻ではないため、異なるロジックで処理します。 通常、ODBC警告はアプリケーションのログに記録するだけで十分ですが、ODBCエラーはプログラムで処理する必要があります。

パブリック・メンバー

メンバー	説明
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形式の出力可能なエラー・メッセージです。

パブリック・メソッド

メソッド	説明
ostream()	エラーをストリームに出力します。

ostream()

friend ostream& operator<<(ostream&, TTStatus&)

このメソッドを使用すると、エラーをストリームに出力できます。

使用方法

TTEXCEPTプリプロセッサ変数を定義して、ライブラリをビルドする必要があります。 エラーが発生した場合は、必ずTTStatusオブジェクトが例外としてスローされます。 これによって、C++アプリケーションで{try/catch}による障害の検出とリカバリが可能となります。

例4-1に、TTEXCEPTを定義したTTStatusの使用方法を示します。

例4-1 TTEXCEPTを定義したTTStatusの使用

try {
  cmd1.Prepare(&conn, "select * from foo", stat);
  cmd2.Prepare(&conn, "insert into foo values(?,?,?)",
               stat);
  cmd3.Prepare(&conn, "update foo set x = ? where y=?",
               stat);
  conn.Commit(stat);
}
catch (TTStatus st) {
  cerr << "Error preparing statements: " << st << endl;
  // Rollback, exit(), throw -- whatever is appropriate
}

例4-2 TTStatusに対するTTErrorおよびTTWarningのエラー・レポート

ODBCエラーが発生するとTTErrorオブジェクトが、ODBC警告が発生するとTTWarningオブジェクトがスローされます。 この例では、エラー処理のTTErrorおよびTTWarningを示します。

// catching TTError & TTWarning exceptions
try {
  // some TTClasses method calls
}
catch (TTWarning warn) {
   cerr << "Warning encountered: " << warn << endl;
}
catch (TTError err) {
    cerr << "Error encountered: " << err << endl;
}

TTConnection

TTConnectionクラスは、TimesTen Databaseに対する接続という概念をカプセル化します。 TTConnectionは、ODBC HDBCハンドルの付加価値C++ラッパーとみなすことができます。

使用方法

TimesTenを使用するすべてのアプリケーションは、1つ以上のTTConnectionオブジェクトを作成する必要があります。

同時に複数のスレッドからTimesTenを使用するマルチスレッド・アプリケーションは、TTConnectionオブジェクトを2つ以上作成する必要があります。次のいずれかの方法を使用します。

• スレッドの作成時に、各スレッドに1つのTTConnectionオブジェクトを作成します。

• アプリケーション・プロセスの開始時に、TTConnectionオブジェクトのプールを作成します。それらはプロセス内の複数のスレッドで共有されます。 このオプションの詳細は、「TTConnectionPool」を参照してください。

TimesTen接続は、親プロセスから継承できません。 プロセスが、子プロセスを作成する前にデータベース接続を開いた場合、子が同じ接続を使用することはできません。

アプリケーションにとっては、TimesTenへの接続と切断を絶えず繰り返すと、パフォーマンスが低下するので好ましくありません。そのかわりに、アプリケーション・プロセスの開始時にデータベース接続を確立し、そのプロセスの存続中はそれを再利用します。

パブリック・メンバー

なし

パブリック・メソッド

メソッド	説明
Connect()	TimesTenデータ・ストアへの新しい接続を開きます。
Disconnect()	TimesTenデータ・ストアへの接続を閉じます。
Rollback()	最後のCommit()またはRollback()メソッドへのコールの後に、この接続を介して行われたデータベースの変更をロールバックします。
isConnected()	オブジェクトがTimesTenに接続されている場合はTRUEを返します。
getHdbc()	この接続に関連付けられたODBCレベル「HDBC」を返します。
SetIsoReadCommitted()	接続のトランザクション分離レベルをTXN_READ_COMMITTEDに設定します。
SetIsoSerializable()	接続のトランザクション分離レベルをTXN_SERIALIZABLEに設定します。
CheckpointBlocking()	TimesTen組込みプロシージャttCkptBlockingをコールして、データ・ストアに対するブロック・チェックポイント処理を実行します。
CheckpointNonBlocking()	TimesTen組込みプロシージャttCkptをコールして、データ・ストアに対するファジー・チェックポイント処理を実行します。
DurableCommit()	データ・ストアに対する永続コミット操作を実行します。
SetLockWait()	TimesTen組込みプロシージャttLockWaitをコールして、接続のロック・タイムアウト間隔を設定します。
SetPrefetchCloseOn()	TT_PREFETCH_CLOSE接続オプションを有効にします。これは、TimesTenへのクライアント/サーバー接続でのSELECT問合せのパフォーマンスを最適化する場合に有効です。
SetPrefetchCloseOff()	TT_PREFETCH_CLOSE接続オプションを無効にします。
SetPrefetchCount()	TimesTen ODBCドライバSQLFetchコールがSELECT文をプリフェッチする行数を、ユーザー・アプリケーションによって調整できます。
SetAutocommitOff()	接続のAUTOCOMMITを無効に設定します。
SetAutoCommitOn()	接続のAUTOCOMMITを有効に設定します。
GetTTContext()	接続のコンテキスト値を返します。

Connect()

void Connect(const char* connStr, TTStatus&)

TimesTenデータ・ストアへの新しい接続を開きます。 connStrパラメータで指定された接続文字列を使用して接続が作成されます。

例4-3 Connect()メソッドの使用およびエラーの確認

エラーが発生するとTTStatusオブジェクトが例外としてスローされます。 このメソッドをコールすると、多くの場合無視しても安全な警告が返されます。 Connect()メソッドを使用する場合は、次のロジックが推奨されます。

TTWarningおよびTTErrorはTTStatusのサブクラスであることに注意してください。

TTConnection conn;
TTStatus stat;
...

try {
  conn.Connect("DSN=mydsn", stat);
}
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
}

Disconnect()

void Disconnect(TTStatus&)

TimesTenデータ・ストアへの接続を閉じます。 エラーが発生するとTTStatusオブジェクトが例外としてスローされます。

Commit()

void Commit(TTStatus&)

TimesTenデータベースにトランザクションをコミットします。 最後のCommit()またはRollback()メソッドへのコールの後に、この接続で実行された他のすべての操作がコミットされます。 エラーが発生するとTTStatusオブジェクトが例外としてスローされます。

Rollback()

void Rollback(TTStatus&)

トランザクションを中止します。 最後のCommit()またはRollback()メソッドへのコールの後に、この接続を介して行われたデータベースの変更が元に戻されます。 エラーが発生するとTTStatusオブジェクトが例外としてスローされます。

isConnected()

bool isConnected()

オブジェクトが（Connect()メソッドによって）TimesTenに接続されている場合はTRUE、そうでない場合はFALSEを返します。

getHdbc()

HDBC getHdbc()

この接続に関連付けられたODBCレベル「HDBC」を返します。

SetIsoReadCommitted()

void SetIsoReadCommitted(TTStatus &)

接続のトランザクション分離レベルをTXN_READ_COMMITTEDに設定します。コミット読取り分離レベルは、単一トランザクションの性能と複数接続の優れた同時実行性という最善の組合せを提供します。

SetIsoSerializable()

void SetIsoSerializable(TTStatus &)

接続のトランザクション分離レベルをTXN_SERIALIZABLEに設定します。通常、シリアライズ可能分離レベルは個別のトランザクションでは優れた性能を提供しますが、同時実行性はきわめて低下します。 ほぼすべての状況下で、シリアライズ可能分離レベルよりもコミット読取り分離レベル（「SetIsoReadCommitted()」を参照）の方が適切です。

CheckpointBlocking()

void CheckpointBlocking(int timeout, int retries, TTStatus &)

TimesTenのttCkptBlocking組込みプロシージャをtimeoutおよびretriesパラメータ付きでコールして、データ・ストアに対してブロッキング・チェックポイント処理を実行します。

ttCkptBlockingの詳細は、『Oracle TimesTen In-Memory Databaseリファレンス』を参照してください。

CheckpointNonBlocking()

void CheckpointNonBlocking(TTStatus &)

注意: これは、適したチェックポイントのタイプです。

TimesTen組込みプロシージャttCkptをコールして、データ・ストアに対するファジー・チェックポイント処理を実行します。

ttCkptの詳細は、『Oracle TimesTen In-Memory Databaseリファレンス』を参照してください。

DurableCommit()

void DurableCommit(TTStatus &)

データ・ストアに対する永続コミット操作を実行します。 永続コミット操作により、インメモリー・トランザクション・ログ・バッファがディスクにフラッシュされます。 このメソッドでは、TimesTen組込みプロシージャttDurableCommitがコールされます。

ttDurableCommitの詳細は、『Oracle TimesTen In-Memory Databaseリファレンス』を参照してください。

SetLockWait()

void SetLockWait(int secs, TTStatus &)

TimesTen組込みプロシージャttLockWaitをパラメータ（secs）付きでコールして、接続のロック・タイムアウト時間を設定します。通常、ほとんどのアプリケーションでは2、3秒のロック・タイムアウトで十分です。デフォルトのロック・タイムアウト時間は10秒です。

ttLockWaitの詳細は、『Oracle TimesTen In-Memory Databaseリファレンス』を参照してください。

SetPrefetchCloseOn()

void SetPrefetchCloseOn(TTStatus &)

TT_PREFETCH_CLOSE接続オプションを有効にします。 これは、TimesTenへのクライアント/サーバー接続でのSELECT問合せのパフォーマンスを最適化する場合に有効です。このメソッドは、直接接続のTimesTenアプリケーション（非クライアント/サーバー・プログラムなど）に対しては利点がないことに注意してください。

TT_PREFETCH_CLOSEの詳細は、『Oracle TimesTen In-Memory Database C開発者ガイド』のTimesTenデータの行のバルク・フェッチに関する説明を参照してください。

SetPrefetchCloseOff()

void SetPrefetchCloseOff(TTStatus &)

TT_PREFETCH_CLOSE接続オプションを無効にします。

SetPrefetchCount()

void SetPrefetchCount(int numrows, TTStatus &)

TimesTen ODBCドライバがSELECT文に対して内部で一度にフェッチする行数を、ユーザー・アプリケーションによって調整できます。 numrowsの値の範囲は1から128である必要があります。

注意: このメソッドは、TTCmd::FetchNext()を複数回実行することと同等ではありません。 そのかわりに、このパラメータを適切に使用すると、TTCmd::FetchNext()の各コールにかかる時間が短縮されます。

TT_PREFETCH_COUNTの詳細は、『Oracle TimesTen In-Memory Database C開発者ガイド』のTimesTenデータの行のバルク・フェッチに関する説明を参照してください。

SetAutocommitOff()

void SetAutoCommitOff(TTStatus &)

接続のAUTOCOMMITを無効に設定します。

TimesTenはAUTOCOMMITが無効の場合にのみ最適な性能で実行されるため、このメソッドはTTConnection::Connect()によって自動的にコールされることに注意してください。

SetAutoCommitOn()

void SetAutoCommitOn(TTStatus &)

接続のAUTOCOMMITを有効に設定します。 つまり、すべてのSQL文が独自のトランザクションで実行されます。

通常、TimesTenはAUTOCOMMITを無効にした方がはるかに高速で実行されることに注意してください。

AUTOCOMMITが無効の場合、SELECT文をコミットするには、TTCmd::Close()を明示的にコールする必要があります。

GetTTContext()

void GetTTContext(char * output, TTStatus &)

接続のコンテキスト値を返します。 このコンテキスト値はTimesTenデータ・ストアへの接続ごとに一意となります。 たとえば、接続のコンテキストは、TimesTenユーティリティttStatusを使用してPIDとTimesTen接続を相関させるために使用できます。

コンテキスト値はoutputパラメータを介して返されます。このメソッドはoutputパラメータにCHAR[17]以上の配列を指定してコールする必要があります。

このメソッドにより、TimesTen組込みプロシージャttContextがコールされます。 ttContextの詳細は、『Oracle TimesTen In-Memory Database C開発者ガイド』を参照してください。

TTCmd

アプリケーション・プログラムで複数回使用される単一のSQL文をカプセル化します。 TTCmdは、ODBC HSTMTハンドルの付加価値C++ラッパーとみなすことができます。

パブリック・メンバー

なし

TTCmdには、次の3種類のパブリック・メソッドがあります。

• パブリック・メソッド

• TTCmdオブジェクトのプロパティを取得するためのパブリック・メソッド

• バッチ操作のためのパブリック・メソッド

パブリック・メソッド

メソッド	説明
Prepare()	SQL文とTTCmdを関連付けます。
RePrepare()	文の再準備を可能にします。
Execute()	実行のために準備されたSQL文を起動します。
ExecuteImmediate()	事前に準備されていないSQL文を起動します。
FetchNext()	応答セットの行を1行ずつフェッチします。行のフェッチに成功した場合は0を、フェッチする行がなくなった場合は1を返します。
Close()	アプリケーションでの行のフェッチが終了したら、応答セットを閉じます。
Drop()	準備済のSQL文とそれに関連付けられたすべてのリソースを解放します。
setQueryTimeout()	問合せのタイムアウト値を設定します。
setQueryThreshold()	SQL文の実行時間が指定した値を超えたときに、サポート・ログに警告を書き込み、SNMPトラップをスローするためのしきい値を設定します。
setMaxRows()	SELECT文によって返される行の数に制限を設定します。
getMaxRows()	SELECT文によって返される行の数の現在の制限を返します。
getRowCount()	最近実行されたSQL操作の影響を受けた行の数を返します。
setParam()	準備済のSQL文を実行する前にパラメータの値を設定します。
setParamNull()	準備済のSQL文を実行する前にパラメータの値をNULLに設定します。
getParamPrecision()	準備済の文に指定されたパラメータの精度を返します。
getParamScale()	準備済の文に指定されたパラメータのスケールを返します。
getParamNull()	指定されたパラメータをNULLにできるかどうかを示します。
getColumn()	特定の列に関連付けられた値を返します。
isColumnNull()	指定された列の値がNULLかどうかを示します。
getColumnLength()	指定された列の長さ（バイト）を返します。
getColumnNullable()	応答セットの現在の行の列値を返して、列値がNULLかどうかを示します。
getNextColumn()	応答セットの次の行の列値を返します。
getNextColumnNullable()	応答セットの次の行の列値を返して、列値がNULLかどうかを示します。
getQueryThreshold()	問合せのしきい値を取得します。
printColumn()	指定された列を出力ストリームに出力します。

TTCmdオブジェクトのプロパティを取得するためのパブリック・メソッド

メソッド	説明
getNParameters()	入力パラメータの数を返します。
getNColumns()	出力列の数を返します。
getParamType()	指定されたパラメータのODBCデータ型を返します。
getColumnName()	指定された列の名前を返します。
getColumnType()	指定された列のODBCデータ型を返します。
getColumnPrecision()	指定された列の精度を返します。
getColumnScale()	指定された列のスケールを返します。

バッチ操作のためのパブリック・メソッド

メソッド	説明
PrepareBatch()	INSERT、UPDATEおよびDELETE文のバッチ処理を準備します。
BindParameter()	PrepareBatch()を使用してコンパイルされた文の値の配列をバインドします。
setParamLength()	準備済の文を実行する前に、バインドされたいずれかのパラメータ値の長さ（バイト）を設定します。
setParamNull()	準備済の文を実行する前に、バインドされたいずれかのパラメータをNULLに設定します。
ExecuteBatch()	PrepareBatch()によって実行のために準備されたSQL文を起動します。バッチ内の更新された行数を返します。

Prepare()

void Prepare(TTConnection*, const char* sqlP, TTStatus&)

このメソッドは、SQL文とTTCmdを関連付けます。次の3つのパラメータをとります。

• TTConnection::Connect()へのコールによってデータベースに接続されている必要のあるTTConnectionオブジェクトへのポインタ

• 準備されているSQL文字列であるconst char *パラメータ

• TTStatusオブジェクト

TTCmdを使用する前に、SQL文（SELECT、INSERT、UPDATEまたはDELETE）を関連付ける必要があります。 この関連付けは、Prepare()メソッドを使用して行われます。このメソッドは、SQL文が効率的に実行されるように、SQL文のコンパイルおよび最適化も行います。 Prepare()メソッドは文を実行しません。

通常、TimesTenでは、性能の向上のために文はパラメータ化されます。次のようなSQL文を考えてみます。

SELECT col1 FROM table1 WHERE C = 10
SELECT col1 FROM table1 WHERE C = 11

これよりも、パラメータ化された1つの文を準備し、それを複数回実行した方がより効率的です。

SELECT col1 FROM table1 WHERE C = ?

「?」の値は、TTCmd::setParam()メソッドを使用して実行時に指定されます。

ODBCを直接使用する場合と違い、列またはパラメータを明示的にSQL文にバインドする必要はありません。 TTCmdは、準備する際にすべての必要な列とパラメータを自動的に定義しバインドします。

Prepareは相対的に負荷の高い操作であることに注意してください。 アプリケーションによって、（TTConnection::Connect()を使用して）TimesTenへの接続が確立される際に、その接続に関連付けられたすべてのTTCmdオブジェクトが準備されます。 エラーが発生するとTTStatusオブジェクトが例外としてスローされます。

RePrepare()

void RePrepare(TTConnection *cP, TTStatus & stat)

このメソッドは、文の再準備を可能にします。このメソッドは、準備済の文の文ハンドルが無効の場合にのみ有効です。

Execute()

void Execute(TTStatus&)

このメソッドは、実行のために準備されたSQL文を起動します。

必要なパラメータ値がsetParam()メソッドによって定義された後、Executeを使用して、Prepare()メソッドによって事前に準備済のSQL文を起動します。

SQL文がSELECT文の場合は、このメソッドによって問合せが実行されますが、結果セットから行が返されません。 FetchNext()メソッドを使用すると、結果セットから一度に1行ずつフェッチされます。 該当するすべての行がフェッチされたら、Close()メソッドを使用して結果セットを閉じます。 SELECT以外のSQL文の場合は、カーソルがオープンされないため、Close()メソッドをコールする必要はありません。 エラーが発生するとTTStatusオブジェクトが例外としてスローされます。

ExecuteImmediate()

int ExecuteImmediate(TTConnection*, const char * sqlP, TTStatus& stat)

このメソッドは、事前に準備されていないSQL文を起動します。

数回だけ実行されるSQL文については、Prepare()およびExecute()のかわりにExecuteImmediate()を使用すると便利です。 DDL文（CREATE TABLE、DROP TABLEなど）や、使用頻度が低く結果セットを返さないDML文（DELETE FROM table_nameなど）にExecuteImmediate()を使用します。

ExecuteImmediate()は、結果セットを返すSQL文と互換性がありません。 また、ExecuteImmediate()によって実行された文は、後でgetRowCount()（DML操作によって影響を受けた行の数を取得する）を使用して問い合せることができません。 このため、ExecuteImmediate()は自動的にgetRowCount()をコールし、その値がこのメソッドの整数の戻り値となります。

FetchNext()

int FetchNext(TTStatus& stat)

Execute()メソッドを使用して準備済のSQL SELECT文を実行した後、FetchNext()メソッドを使用して、応答セットから一度に1行ずつフェッチします。

応答セットから1行をフェッチした後に、オーバーロードされたバージョンのgetColumn()メソッドの1つを使用して、現在の行から値をフェッチします。

応答セットに行がなくなると、FetchNext()は1を返します。 行が返されると、FetchNext()は0を返します。

Execute()メソッドを使用してSELECTを実行した後、要求されるすべての行がフェッチされてから、Close()メソッドで応答セットを閉じる必要があります。 Close()メソッドをコールした後は、FetchNext()メソッドを使用して応答セットからそれ以上の行をフェッチできないことに注意してください。 エラーが発生するとTTStatusオブジェクトが例外としてスローされます。

Close()

void Close(TTStatus&)

Execute()メソッドを使用してSQL SELECT文を実行すると、応答セットから行をフェッチするために使用できるカーソルがオープンされます。 アプリケーションでの行のフェッチが完了したら、Close()メソッドを使用してカーソルをクローズする必要があります。

応答セットのクローズに失敗すると、行のロックが保持される時間が長くなりすぎるため、同時実行性の問題、メモリー・リークおよびその他のエラーが発生する可能性があります。 エラーが発生するとTTStatusオブジェクトが例外としてスローされます。

Drop()

void Drop(TTStatus&)

準備済のSQL文を今後使用しない場合は、Drop()メソッドをコールして、その文とそれに関連付けられたリソースを解放できます。 再度Prepare()をコールすると、TTCmdオブジェクトを別の文に再利用できます。

複数のTTCmdオブジェクトを使用して複数のSQL文を実行した方が、より効率的です。 特定のSQL文を今後使用しないことが確実な場合にのみ、Drop()メソッドを使用してください。 エラーが発生するとTTStatusオブジェクトが例外としてスローされます。

setQueryTimeout()

void setQueryTimeout(const int nSecs, TTStatus&)

このメソッドでは、必要に応じて、問合せでタイムアウト値を設定して、アプリケーションによって長時間実行問合せを停止できます。 nSecsの値は、タイムアウトの時間（秒）を指定します。

デフォルトの問合せタイムアウト値は存在しないことに注意してください。

setQueryThreshold()

void TTCmd::setQueryThreshold(const int seconds, TTStatus &stat)

このメソッドは、SQL文の実行時間が指定した値を超えたときに、サポート・ログに警告を書き込み、SNMPトラップをスローするためのしきい値を設定します。

setMaxRows()

void setMaxRows(const int nRows, TTStatus &stat)

このメソッドは、SELECT文によって返される行数に制限を設定します。結果セットの行数が設定された上限を超える場合、設定された最大行数を超えてフェッチすると、文はSQL_NO_DATA_FOUNDを返します。 eof()メソッドがコールされると、TTCmdオブジェクトはTRUEを返します。デフォルトでは、すべての行が返されます。 すべての行を返すように制限をリセットするには、nRowsを0に設定してsetMaxRows()をコールします。この制限はSELECT文に対してのみ意味があります。

getMaxRows()

int getMaxRows(TTStatus &stat)

このメソッドは、SELECT文によってこのTTCmdオブジェクトから返される行数について現在設定されている上限を返します。戻り値0は、すべての行が返されることを示します。

getRowCount()

int getRowCount()

このメソッドをExecute()の直後にコールして、直前に実行されたSQL操作の影響を受けた行の数を返すことができます。 たとえば、10行を削除するDELETE文が実行された後には、getRowCount()は10を返します。

setParam()

void setParam(int pno, ...)

この項では、オーバーロードされたすべてのsetParam()バージョンについて説明します。

準備済のSQL文を実行する前に、様々なsetParam()バージョンを使用してパラメータの値を設定します。 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()メソッドのコール時の値ではありません。

表4-1に、サポートされるSQLデータ型と、各パラメータ型での使用に適したsetParam()のバージョンを示します。 表に示されていないSQLデータ型は、このバージョンのTTClassesではサポートされないことに注意してください。

注意: この表では、長さlenの単位はバイトです。

表4-1 サポートされるデータ型に対するTTCmd::setParam()のバージョン

データ型	サポートされるsetParamのバージョン
TT_TINYINT	setParam(int, unsigned char)
TT_SMALLINT	setParam(int, SQLSMALLINT)
TT_INTEGER	setParam(int, SQLINTEGER)
TT_BIGINT	setParam(int, SQLBIGINT)
BINARY_FLOAT	setParam(int, float)
BINARY_DOUBLE	setParam(int, double)
NUMBER TT_DECIMAL	setParam(int, char*) setParam(int, const char*) setParam(int, SQLTINYINT) setParam(int, SQLSMALLINT) setParam(int, SQLINTEGER) setParam(int, SQLBIGINT) 注意: 整数型のメソッドは、たとえばNUMBER(8)やNUMBER(8,0)など、スケール・パラメータが0（ゼロ）で宣言された列にのみ適しています。
TT_CHAR CHAR TT_VARCHAR VARCHAR2	setParam(int, char*) setParam(int, const char*)
TT_NCHAR NCHAR NVARCHAR2	setParam(int, SQLWCHAR*, int len)
BINARY VARBINARY	setParam(int, const void*, int len)
DATE TT_TIMESTAMP TIMESTAMP	setParam(int, TIMESTAMP_STRUCT*)
TT_DATE	setParam(int, DATE_STRUCT*)
TT_TIME	setParam(int, TIME_STRUCT*)

setParamNull()

void setParamNull(int pno)

このメソッドを使用して、パラメータ番号pnoの値をSQLのNULL値に指定できます。

「setParam()」を参照してください。

getParamPrecision()

int getParamPrecision(int pno)

このメソッドは、パラメータ番号pnoの精度を返します。

getParamScale()

int getParamScale(int pno)

このメソッドは、パラメータ番号pnoのスケールを返します。

getParamNull()

bool getParamNull(int pno);

このメソッドは、パラメータ番号pnoをNULLにできるかどうかを示します。

getColumn()

void getColumn (int cno, ...)

getColumn()メソッドおよびgetColumnNullable()メソッド（簡単に説明）を使用して、応答セットの現在の行の列値をフェッチできます。 getColumn()およびgetColumnNullable()メソッドを使用するには、まずFetchNext()メソッドを使用して、SELECT文の応答セットから最初（または次）の行をフェッチする必要があります。 SQL文はExecute()メソッドを使用して実行されます。

getColumn()メソッドは、特定の列に関連付けられた値を返します。 列は序数で参照され、「1」はSELECT文で指定された最初の列を示します。 すべての場合において、getColumn()メソッドに渡される最初の引数は、値がフェッチされる列の序数です。 getColumn()メソッドに渡される2番目の引数は、指定された列の値を受け取る変数のポインタです。この引数の型は、返される列の型に依存します。

このバージョンのTTClassesライブラリは、大規模なデータ型の変換セットをサポートしません。 準備済のSQLの出力列ごとに、オーバーロードされた適切なバージョンのgetColumn()をコールする必要があります。 誤ったバージョンをコールする（たとえば、整数の列をchar*値にフェッチしようとする）と、プログラム障害が発生するおそれがあります。

整数型のメソッドには、SQLTINYINT、SQLSMALLINT、SQLINTEGERまたはSQLBIGINTのいずれかの関数が含まれています。これらのメソッドは、たとえばNUMBER(p)やNUMBER(p,0)など、スケール・パラメータが0（ゼロ）に設定された列にのみ適しています。前述の関数の精度範囲を次に示します。

関数	精度範囲
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*)

表4-2に、サポートされるSQLデータ型と、各パラメータ型での使用に適したgetColumn()およびgetColumnNullable()のバージョンを示します。

注意: この表では、長さlenPの単位はバイトです。

表4-2 サポートされるデータ型に対するTTCmd::getColumn()/getColumnNullable()のバージョン

データ型	サポートされるgetColumnのバージョン
TT_TINYINT	getColumn(int cno, unsigned char*) getColumnNullable(int cno, SQLTINYINT*)
TT_SMALLINT	getColumn(int cno, SQLSMALLINT*) getColumnNullable(int cno, SQLSMALLINT*)
TT_INTEGER	getColumn(int cno, SQLINTEGER*) getColumnNullable(int cno, SQLINTEGER*)
TT_BIGINT	getColumn(int cno, SQLBIGINT*) getColumnNullable(int cno, SQLBIGINT*)
BINARY_FLOAT	getColumn(int cno, float*) getColumnNullable(int cno, float*)
BINARY_DOUBLE	getColumn(int cno, double*) getColumnNullable(int cno, double*)
NUMBER TT_DECIMAL	getColumn(int cno, char**) getColumn(int cno, SQLTINYINT*) getColumn(int cno, SQLSMALLINT*) getColumn(int cno, SQLINTEGER*) getColumn(int cno, SQLBIGINT*) getColumnNullable(int cno, char**) getColumnNullable(int cno, SQLTINYINT*) getColumnNullable(int cno, SQLSMALLINT*) getColumnNullable(int cno, SQLINTEGER*) getColumnNullable(int cno, SQLBIGINT*) 注意: 整数型のメソッドは、スケール・パラメータが0（ゼロ）で宣言された列にのみ適しています。
TT_CHAR CHAR TT_VARCHAR VARCHAR2	getColumn(int cno, char**) getColumnNullable(int cno, char**)
TT_NCHAR NCHAR TT_NVARCHAR NVARCHAR2	getColumn(int cno, SQLWCHAR*) getColumnNullable(int cno, SQLWCHAR*)
BINARY VARBINARY	void getColumn(int cno, void** binPP, int* lenP) void getColumnNullable(int cno, void** binPP, int* lenP)
DATE TT_TIMESTAMP TIMESTAMP	getColumn(int cno, TIMESTAMP_STRUCT*) getColumnNullable(int cno, TIMESTAMP_STRUCT*)
TT_DATE	getColumn(int cno, DATE_STRUCT*) getColumnNullable(int cno, DATE_STRUCT*)
TT_TIME	getColumn(int cno, TIME_STRUCT*) getColumnNullable(int cno, TIME_STRUCT*)

このリリースのTTClassesライブラリでは、他のSQLデータ型はサポートされません。

isColumnNull()

bool isColumnNull(int cno)

このメソッドは、列番号cnoの値がNULLかどうかを決定するもう1つの方法です。

getColumnNullable()メソッドについて、次の説明を参照してください。

getColumnLength()

int getColumnLength(int cno)

このメソッドは、列番号cnoの長さ（バイト）を返します。NULL終了文字はカウントせず、値がNULLの場合はSQL_NULL_DATAを返します。 通常、このメソッドはVARBINARYまたはNVARCHAR2型の列にアクセスする場合のみ有効です。 返される値は、0から列の精度の間の値です。 「getColumnPrecision()」を参照してください。

getColumnNullable()

bool getColumnNullable(int cno, ...)

getColumnNullable()メソッドは、前述のgetColumn()メソッドに類似しています。 ただし、getColumnNullable()メソッドはgetColumn()の動作に加え、値がSQLのNULL擬似値であるかどうかも返します。 値がNULLである場合、2番目のパラメータは特徴的な値（-9999など）に設定され、メソッドの戻り値はTRUEとなります。 値がNULLでない場合、2番目のパラメータが指す変数で値が返され、getColumnNullable()メソッドはFALSEを返します。

「getColumn()」を参照してください。

getNextColumn()

void getNextColumn(int iP, ...)

getNextColumn()メソッドおよび（簡単に説明するところの）getNextColumnNullable()メソッドを使用して、結果セットの次の行の列値をフェッチできます。 getNextColumn()およびgetNextColumnNullable()メソッドを使用するには、まずFetchNext()メソッドを使用して、SELECT文の結果セットから最初の行をフェッチする必要があります。 iPパラメータは内部列番号へのポインタを表します。 getNextColumn()を使用する場合、列は順番にフェッチされます。フェッチする順番は変更できません。

サポートされるSQLデータ型と、各パラメータ型での使用に適したgetColumn()バージョン（前述の説明を参照）については、表4-3を参照してください。 この情報は、getNextColumn()に対して使用できます。

getNextColumnNullable()

bool getColumnNullable(int iP, ...)

getNextColumnNullable()メソッドは、前述のgetNextColumn()メソッドに類似しています。 ただし、getNextColumnNullable()メソッドはgetColumn()の動作に加え、値がSQLのNULL擬似値であるかどうかを返します。 値がNULLである場合、2番目のパラメータは特徴的な値（-9999など）に設定され、メソッドの戻り値はTRUEとなります。 値がNULLでない場合、2番目のパラメータが指す変数で値が返され、getColumnNullable()メソッドはFALSEを返します。

iPパラメータは内部列番号へのポインタを表します。 getNextColumn()を使用する場合、列は順番にフェッチされます。フェッチする順番は変更できません。

サポートされるSQLデータ型と、各パラメータ型での使用に適したgetColumn()バージョンについては、表4-3を参照してください。 この情報は、getNextColumnNullable()に対して使用できます。

getQueryThreshold()

int TTCmd::getQueryThreshold(TTStatus &stat)

問合せのしきい値を取得します。 「setQueryThreshold()」を参照してください。

printColumn()

void printColumn(int cno, STDOSTREAM & os, const char *  nullstring) const

このメソッドは、列番号cnoを出力ストリームに出力します。デバッグまたはデモ・プログラム用に使用します。

使用方法

プログラムで複数回実行される各SQL文には、独自のTTCmdオブジェクトが必要です。 これらのTTCmdオブジェクトは、プログラムの初期化時にそれぞれ1回準備され、プログラムの実行時にExecute()メソッドで複数回実行されます。

ExecuteImmediate()メソッドは、1回 だけ実行する必要のあるデータベース操作でのみ使用します。 ExecuteImmediate()はどのタイプのSELECT文とも互換性がないことに注意してください。 かわりに、すべての問合せでPrepare()とExecute()を使用する必要があります。 また、ExecuteImmediate()は、後で、挿入、更新または削除された行数を調べるために、getRowcount()を使用してポーリングされるINSERT、UPDATEまたはDELETE文とも互換性がありません。 これらの制限は、一部の特別な状況（表の作成または削除など）を除き、ExecuteImmediate()の使用を避けるために課されています。

準備済のTTCmdオブジェクトのプロパティを取得するためのメソッド

準備済のTTCmdオブジェクトの、バインドされた入力パラメータおよび出力列のプロパティについて問い合せる場合に有効なメソッドがいくつかあります。通常、これらのメソッドでは、文が事前に準備されている場合にのみ、有効な結果が得られます。

getNParameters()

int getNParameters()

このメソッドは、入力パラメータの数を返します。

getNColumns()

int getNColumns()

このメソッドは、出力列の数を返します。

getParamType()

int getParamType(int pno)

このメソッドは、パラメータ番号pnoのデータ型を返します。 返される値は、sql.hに見られる、ODBC型（SQL_INTEGER、SQL_REAL、SQL_BINARY、SQL_CHARなど）です。その他のTimesTen型（SQL_WCHAR、SQL_WVARCHAR）は、TimesTenヘッダー・ファイルtimesten.hで見られます。

getColumnName()

const char * getColumnName(int cno)

このメソッドは、列番号cno の名前を返します。

getColumnType()

int getColumnType(int cno)

このメソッドは、列番号cnoのデータ型を返します。 返される値は、sql.hに見られる、パラメータのODBC型（SQL_INTEGER、SQL_REAL、SQL_BINARY、SQL_CHARなど）です。その他のTimesTen型（SQL_WCHAR、SQL_WVARCHAR）は、TimesTenヘッダー・ファイルtimesten.hで見られます。

getColumnPrecision()

int getColumnPrecision(int cno)

このメソッドは、列番号 cnoの精度を返します。通常、この値は、表のCHAR、VARCHAR2、BINARY、VARBINARY、NCHARおよびNVARCHAR2型の列から出力を生成する場合にのみ重要です。

getColumnScale()

int getColumnScale(int cno)

このメソッドは、列番号cno のスケールを返します。

バッチ操作

TimesTenは、挿入、更新および削除のバッチ操作のためにODBC関数SQLBindParamsをサポートします。 TTClassesはSQLBindParamsへのインタフェースを提供します。

TTClassesでのバッチ操作は、非バッチ操作と同様に実行されます。 最初に、SQL文がPrepareBatch()によってコンパイルされます。 次に、その文の各パラメータが、BindParameter()によって値の配列にバインドされます。 最後に、ExecuteBatch()によって文が実行されます。 通常のTTClasses（非バッチ）操作との類似性に注意してください。Prepareによって文がコンパイルされ、すべてのパラメータのバインドの自動的に実行され、Execute()によって文が実行されます。

バッチ操作の使用例については、TTClassesのサンプル・プログラムbulktestを参照してください。

この項では、TTClassesユーザー向けに、バッチの挿入/更新/削除機能を公開するTTCmdメソッドについて説明します。

PrepareBatch()

void PrepareBatch(TTConnection*, const char * sqlP,
     TTCmd::TTCMD_USER_BIND_LEVEL level,
     unsigned short batchSize, TTStatus&)

PrepareBatch()は、INSERT、UPDATEまたはDELETE文のバッチ操作に使用されるPrepare()の類似メソッドです。 TTConnection*、sqlPおよびTTStatus&パラメータは、Prepare()メソッドの場合と同様に使用されます。

levelパラメータに有効な値は次の1つのみです。

TTCmd::TTCMD_USER_BIND_PARAMS

batchSizeパラメータは、ExecuteBatch()への後続のコールによって実行される挿入/更新/削除操作の最大数を指定します。

BindParameter()

void BindParameter(int pno, unsigned short batchSize,
      TYPE*, [SQLLEN*], TTStatus&)

オーバーロードされたBindParameter()メソッドは、PrepareBatch()によってコンパイルされた文について、値の配列（各パラメータに1つ）をバインドするために使用されます。 このコールのbatchSizeの値は、PrepareBatch()で指定されたbatchSizeの値と一致する必要があります。 同様に、バインドされた配列には、PrepareBatch()のバインドされた配列以上の値が含まれる必要があります。 各パラメータの正しい型を判別する必要があります。 不適切な型が指定されると、TTLog::TTLOG_ERRロギング・レベルのTTClassesグローバル・ロギング機能に実行時エラーが書き込まれることに注意してください。

ExecuteBatch()を起動するたびに、アプリケーションで事前にこれらの配列に有効なパラメータ値を設定する必要があります。

SQL型（SQL_BINARY、SQL_VARBINARY、SQL_WCHARおよびSQL_WVARCHAR）については、追加のSQLLEN*パラメータ（パラメータの長さの配列）（バイト）が必要です。 この追加配列の長さは、batchSizeの長さ以上であり、ExecuteBatch()のコール前に、有効な長さの値が設定されている必要があります。

表4-3に、サポートされるSQLデータ型と、各パラメータ型での使用に適したBindParameter()のバージョンを示します。

表4-3 サポートされるデータ型に対するTTCmd::BindParameter()のバージョン

SQLデータ型	サポートされるBindParameterのバージョン
TT_TINYINT	BindParameter(... SQLTINYINT*...)
TT_SMALLINT	BindParameter(...SQLSMALLINT*...)
TT_INTEGER	BindParameter(...SQLINTEGER*...)
TT_BIGINT	BindParameter(...SQLBIGINT*...)
BINARY_FLOAT	BindParameter(...float*...)
BINARY_DOUBLE	BindParameter(...double*...)
NUMBER TT_DECIMAL	BindParameter(...char**...)
TT_CHAR CHAR TT_VARCHAR VARCHAR2	BindParameter(...char**...)
TT_NCHAR NCHAR TT_NVARCHAR NVARCHAR2	BindParameter(...SQLWCHAR**, SQLLEN*...)
BINARY VARBINARY	BindParameter(...const void**, SQLLEN*...)
DATE TT_TIMESTAMP TIMESTAMP	BindParameter(... TIMESTAMP_STRUCT*...)
TT_DATE	BindParameter(...DATE_STRUCT*...)
TT_TIME	BindParameter (...TIME_STRUCT*...)

setParamLength()

setParamLength(int pno, unsigned short rowno, int len)

このメソッドは、ExecuteBatch()をコールする前に、バインドされたいずれかのパラメータ値の長さを設定します。 pnoパラメータは、文内のどのパラメータを設定するかを指定します。 rownoパラメータは、長さを設定する行を指定します。 lenパラメータは、設定される長さ（バイト）を指定します。NULL終了文字はカウントしません。またはNULL終了文字としてSQL_NTSに指定することができます。 （これは、SQL_NULL_DATAにも設定できますが、TimesTenでは、setParamNull()メソッドをこの目的で提供しています。）

SQL_BINARY、SQL_VARBINARY、SQL_WCHARおよびSQL_WVARCHAR以外の型については、ExecuteBatch()をコールする前にパラメータの長さを明示的に設定するために使用できるメソッドはこれのみです。 これらの型については、BindParameter()コールの4番目のパラメータであるSQLLEN*配列の操作によって、長さを明示的に設定することもできます。

setParamNull()

setParamNull(int pno, unsigned short rowno)

このメソッドは、ExecuteBatch()をコールする前に、バインドされたいずれかのパラメータ値をNULLに設定します。1番目のパラメータpnoは、文内のどのパラメータを設定するかを指定します。2番目のパラメータrownoは、長さを設定する行を指定します。

SQL_BINARY、SQL_VARBINARY、SQL_WCHARおよびSQL_WVARCHAR以外の型については、ExecuteBatch()をコールする前にNULLの値のパラメータを明示的に設定するために使用できるメソッドはこれのみです。 これらの型については、BindParameter()コールの4番目のパラメータであるSQLLEN*配列の操作によって、NULLであることを明示的に設定することもできます。

ExecuteBatch()

void ExecuteBatch(unsigned short numRows, TTStatus&)

このメソッドはバッチ内の更新された行数を返します。 この数は、ODBC SQLSetParamsコールからの*pirowを表します。

PrepareBatch()によってSQL文を準備し、そのSQL文の各パラメータ（「?」）に対してBindParameter()をコールした後、ExecuteBatch()を使用してその文をnumRows回実行します。 numRowsの値は、PrepareBatch()およびBindParameter()コールで指定した、batchSize以下にする必要があります。 アプリケーション・ロジックで必要な場合は、numRowsパラメータをbatchSizeの値より小さくすることは可能です。

アプリケーションでは、ExecuteBatch()をコールする前に、BindParameter()でバインドされたパラメータの配列に有効な値を設定する必要があります。 必要に応じて、setParamNull()によってNULL値を指定できます。

また、例4-4にも、ExecuteBatch()メソッドの使用方法を示します。 （bulktestデモにも、このメソッドの使用方法を示します。）

例4-4 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;
TTStatus stat;

// (assume a connection has already been established)

try {

 insert.PrepareBatch (&connection,
                      (const char*)"insert into batch_table
                       values (?,?)",
                       TTCmd::TTCMD_USER_BIND_PARAMS,
                       BATCH_SIZE
                       stat);

// Commit the prepared statement

connection.Commit(stat);

// Bind the arrays of parameters

insert.BindParameter(1, BATCH_SIZE, int_array, stat);
insert.BindParameter(2, BATCH_SIZE, char_array, stat);

// Execute 5 batches, inserting 5 * BATCH_SIZE rows into
// the database

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

       // 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, stat);

       cerr << "Inserted " << num_ins << " rows." << endl;

       connection.Commit(stat);

   } // for iter

たとえば、列の1つに一意制約が指定されている場合などは、行数（この例では(num_ins）をBATCH_SIZE よりも少なくすることができます。 例4-5のようなコード使用して、この状況を確認し、必要に応じてトランザクションをロールバックできます。

例4-5 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, stat);

       cerr << "Inserted " << num_ins << " rows (expected " <<
           << BATCH_SIZE << " rows)." << endl;

       if (num_ins == BATCH_SIZE) {
        cerr << "Committing batch" << endl;
        connection.Commit(stat);
       }
       else {
        cerr << "Some rows were not inserted as expected, rolling back "
              << "transaction." << endl;
        connection.Rollback(stat);
        break; // jump out of batch insert loop
       }

   } // for iter

TTCmd::ExecuteBatch()の整数出力は、ODBC SQLParamOptionsコールの3番目のパラメータと同等の*pirowです。 SQLParamOptionsの詳細は、『ODBC Programmer's Manual』を参照してください。

TTConnectionPool

TTConnectionPoolクラスは、マルチスレッド・アプリケーションによって、接続のプールの管理に使用されます。

通常、マルチスレッド・アプリケーションは次のいずれかの基本的な方法を使用して作成できます。

• スレッドの数が相対的に少なく、さらにスレッドの存続時間が長い場合は、アプリケーションの存続期間中使用される、異なる接続に各スレッドを割り当てることができます。 この使用例では、TTConnectionPoolクラスは必要ありません。

• プロセス内のスレッドの数が多い場合、またはスレッドの存続時間が短い場合は、アプリケーションの存続期間中使用されるアイドル状態の接続のプールを確立できます。スレッドは、データベース・トランザクションを実行する必要がある場合、プールからアイドル状態の接続を確認し、そのトランザクションを実行して、接続をプールに返します。 これは、TTConnectionPoolクラスを使用した使用例です。

  
  

  注意: 全体のパフォーマンスを最高にするために、データベース・サーバーのCPUごとに1つまたは2つの同時ダイレクト・メモリー・データベース接続を使用することをお薦めします。同時ダイレクト・メモリー・データベース接続の数（接続プールのサイズ）は、常にデータベース・サーバーのCPU数の2倍を超えるようにしてください。 ただし、クライアント/サーバー・モードでは、CPUごとにさらに多くの接続が効率的にサポートされます。

  
  

アプリケーションは、TTConnectionPoolクラスを使用するために、クラスの単一のインスタンスを作成します。 その後、多数のTTConnectionオブジェクトを作成しますが、それらのConnect()メソッド（実際にそれらをTimesTenに接続するメソッド）はコールしません。 アプリケーションはTTConnectionPool::AddConnectionToPool()メソッドを使用して、接続オブジェクトをプールに配置します。 その後、アプリケーションはTTConnectionPool::ConnectAll()をコールして、すべての接続をTimesTenに接続します。 TimesTenを使用するスレッドは、getConnection()メソッドとfreeConnection()メソッドを使用し、アイドル状態の接続を取得して返します。

パブリック・メンバー

なし

パブリック・メソッド

メソッド	説明
AddConnectionToPool()	TTConnectionオブジェクト、またはTTConnectionから導出されたクラスのオブジェクトを接続プールに追加します。
ConnectAll()	すべてのTTConnectionオブジェクトを同時にTimesTenに接続します。
getConnection()	スレッドの接続プールからアイドル状態の接続を確認します。
freeConnection()	別のスレッドへの再割当てができるよう、接続をプールに返します。
DisconnectAll()	接続プール内のすべての接続をTimesTenから切断します。
getStats()	TTConnectionPoolにステータス情報を問い合せます。

AddConnectionToPool()

int AddConnectionToPool(TTConnection*)

このメソッドは、TTConnectionオブジェクト、またはTTConnectionから導出されたクラスのオブジェクトを接続プールに追加するために使用されます。

ConnectAll()

void ConnectAll(const char* connStr, TTStatus&)

AddConnectionToPool()によってTTConnectionオブジェクトが接続プールに追加された後、ConnectAll()メソッドを使用して、すべてのTTConnectionオブジェクトを同時にTimesTenに接続できます。 エラーが発生するとTTStatusオブジェクトが例外としてスローされます。

getConnection()

TTConnection* getConnection(int timeout_millis=0)

スレッドの接続プールからアイドル状態の接続を確認します。 アイドル状態のTTConnectionオブジェクトへのポインタが返されます。 スレッドはその後、トランザクションを実行し、Commit()またはRollback()のいずれかでそれを終了してから、freeConnection()メソッドを使用して接続をプールに返します。

プール内にアイドル状態の接続がない場合は、freeConnection()のコールによって接続がプールに返されるまで、getConnection()をコールするスレッドがブロックされます。オプションのタイムアウトをミリ秒単位で指定できます。 これが指定された場合、getConnection()は、最大でtimeoutミリ秒間、使用可能な接続を待機します。 その時間内に使用可能な接続がなかった場合、getConnection()はコール元にNULLを返します。

freeConnection()

void freeConnection(TTConnection*)

別のスレッドへの再割当てができるよう、接続をプールに返します。アプリケーションでは、トランザクション中の接続を解放しないでください。 freeConnection()をコールする直前に、TTConnection::Commit()またはTTConnection::Rollback()をコールする必要があります。

DisconnectAll()

void DisconnectAll(TTStatus&)

接続プール内のすべての接続をTimesTenから切断します。

アプリケーションでは、プロセス障害の分析とリカバリに関連するオーバーヘッドを回避するために、終了の前にDisconnectAll()をコールする必要があります。 エラーが発生するとTTStatusオブジェクトが例外としてスローされます。

getStats()

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()をコールしていません。

TTGlobal

TTGlobalクラスは、TTClassesのロギング機能を提供します。

パブリック・メンバー

なし

パブリック・メソッド

メソッド	説明
setLogStream()	TTClassesのロギング情報の送信先を指定します。
setLogLevel()	TTClassesロギングの冗長レベルを指定します。
disableLogging()	TTClassesのロギングを無効にします。

setLogStream()

static void setLogStream(ostream & str)

TTClassesのロギング情報の送信先を指定します。 デフォルトでは、TTClassesロギングが有効な場合、stderrにロギングします。 このメソッドを使用すると、ロギングをapp_log.txtに設定する次の例のように、ユーザー・アプリケーションはロギングをファイル（または他の任意のostream&）に指定できます。

ofstream log_file("app_log.txt");
TTGlobal::setLogStream(log_file);

setLogLevel()

static void setLogLevel(TTLog::TTLOG_LEVEL level)

このメソッドは、TTClassesロギングの冗長レベルを指定します。 表4-4に、TTClassesのロギング・レベルを示します。これらのレベルは累積されます。

表4-4 TTClassesのロギング・レベル

ロギング・レベル	説明
TTLog::TTLOG_NIL	ロギングは行われません。
TTLog::TTLOG_FATAL_ERR	致命的エラー（TTClassesメソッドの重大な誤用）が記録されます。
TTLog::TTLOG_ERR	すべてのエラー（SQL_ERRORリターン・コードなど）が記録されます。
TTLog::TTLOG_WARN	（デフォルト）警告とTTCmd::Prepare()に対するすべてのコールが記録されます（準備中のSQL文字列も含む）。データベース・オプティマイザのすべての問合せ計画が出力されます。
TTLog::TTLOG_INFO	情報メッセージ（TTCmdおよびTTConnectionオブジェクトのほとんどのメソッドに対するコールなど）も記録されます。 該当するSQL文字列も含まれます。
TTLog::TTLOG_DEBUG	デバッグ用の追加情報（TTCmd::Execute()に対する各コールにバインドされたすべてのパラメータの値など）も記録されます。

たとえば、ロギング・レベルをTTLog::TTLOG_ERRに設定するには、次の行をプログラムに追加します。

TTGlobal::setLogLevel (TTLog::TTLOG_ERR);

disableLogging()

static void disableLogging()

このメソッドは、すべてのTTClassesロギングを無効にします。次の2つの文は同一であることに注意してください。

TTGlobal::disableLogging();
TTGlobal::setLogLevel (TTLog::TTLOG_NIL);

TTGlobalの使用

TTGlobalロギング機能は、TTClassesプログラム内で発生する問題のデバッグに非常に役立つことがあります。 ただし、冗長度の高いロギング・レベル（TTLog::TTLOG_INFOおよびTTLog::TTLOG_DEBUG）の場合は、膨大な出力が生成される可能性があることに注意してください。これらのロギング・レベルは、本番の稼働時ではなく、開発時または不具合の診断時に使用してください。

マルチスレッド・プログラムからロギングする場合は、ディスクへの書込み時に、異なるプログラム・スレッドのログ出力が混合されるという問題が発生するおそれがあります。 この問題を軽減するには、次の例にあるように、ios_base::unitbuf I/Oストリーム・マニピュレータでostreamバッファリングを無効にします。このマニピュレータは、ロギング・レベルTTLog::TTLOG_ERRのapp_log.txtファイルにTTClassesロギングを送信します。

ofstream log_file("app_log.txt");
log_file << std::ios_base::unitbuf;
TTGlobal::setLogStream(log_file);
TTGlobal::setLogLevel(TTLog::TTLOG_ERR);

TTGlobalの使用方法の詳細は、「TTClassesのロギング」を参照してください。

システム・カタログ・クラス

TTCatalogは、データベースのシステム・カタログからのメタデータ読取りを容易にするために、TimesTen C++ Interface Classesに含まれています。

TTCatalogクラスは、TimesTen C++ Interface Classesに含まれる他のクラスを使用するのとは異なります。 TTCatalogコンストラクタは、データベースに接続し、そのシステム・カタログを読み取った後、データベースへの接続を切断し、それ以上データベースと直接相互作用しません。生成されるオブジェクトには、データベース・カタログから読み取られたすべての情報を持ち、ユーザー・プログラムから簡単にアクセスできるデータ構造が含まれます。

各TTCatalogには、TTCatalogTableオブジェクトの配列が含まれます。 各TTCatalogTableには、TTCatalogColumnオブジェクトの配列と、TTCatalogIndexオブジェクトの配列が含まれます。索引によってアクセスする場合、これらの配列へのアクセスは0（ゼロ）ベースです。

TTCatalog内では次のODBC関数が使用されます。

• SQLTables()

• SQLColumns()

• SQLSpecialColumns()

• SQLStatistics()

この項では、次のクラスについて説明します。

• TTCatalog

• TTCatalogTable

• TTCatalogColumn

• TTCatalogIndex

TTCatalog

TTCatalogクラスは、データベース内の表に関するメタデータ情報へのプログラム的なアクセスに使用される、トップ・レベルのクラスです。 TTCatalogオブジェクト内には、TTCatalogTableオブジェクトの内部配列があります。 コンストラクタを除くTTCatalogのすべてのパブリック・メソッドを使用して、そのTTCatalogTable配列への読取り専用アクセスを取得します。

TTCatalogコンストラクタは、TTConnection*パラメータをキャッシュし、すべての内部データ構造を適切に初期化します。

TTCatalog (TTConnection*)

その後、TTCatalogオブジェクトを使用するために、そのfetchCatalogData()メソッド（後述の説明を参照）をコールします。

パブリック・メンバー

なし

パブリック・メソッド

メソッド	説明
fetchCatalogData()	自分自身を構築する際にデータ・ストア内のカタログを読み取って表および索引に関する情報を取得し、それを内部データ構造に格納します。
getNumTables()	ユーザー表とシステム表の両方を含む、データベース内の表の合計数を返します。
getNumUserTables()	データベース内のユーザー表の数を返します。
getNumSysTables()	データベース内のシステム表の数を返します。
getTable()	指定されたデータベース表に対応するTTCatalogTableオブジェクトへの定数参照を返します。
getTable()	（nが指定された）システム内のn番目の表に対応するTTCatalogTableへの定数参照を返します。
getUserTable()	（nが指定された）システム内のn番目のユーザー表に対応するTTCatalogTableへの定数参照を返します。
getTableIndex()	指定された表に対するTTCatalogオブジェクト内の索引を返します。

fetchCatalogData()

fetchCatalogData(TTStatus &)

これは、データ・ストアと相互作用する唯一のメソッドです。 データ・ストアへの接続はコンストラクタによってキャッシュされたため、唯一のパラメータはTTStatusオブジェクトです。 このメソッドは、自身を構築する際にデータベース内のカタログを読み取って表および索引に関する情報を取得し、それを内部データ構造に格納します。

その後、構築されたTTCatalogオブジェクトは完全にオフラインで使用されます。このオブジェクトは、構築後はデータベースに接続されません。

その他のTTCatalogアクセッサ・メソッドのいずれかを使用する前に、このメソッドをコールする必要があります。

次の例に、TTCatalogの使用方法を示します。2つのデータベース・コール後のstat.rcの確認は行いません。

例4-6 カタログ・データのフェッチ

TTConnection conn;
TTStatus stat;
conn.Connect(DSN=TptbmData37, stat);
TTCatalog cat (&conn);
cat.fetchCatalogData(stat);
// 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;

getNumTables()

int getNumTables()

ユーザー表とシステム表の両方を含む、データベース内の表の合計数を返します。

getNumUserTables()

int getNumUserTables()

データベース内のユーザー表の数を返します。

getNumSysTables()

int getNumSysTables()

データベース内のシステム表の数を返します。

対応するgetSysTable()メソッドはありません。

getTable()

const TTCatalogTable & getTable(const char * owner, const char * tblname)

ownerによって所有されるtblnameという名前のデータベース表に対応するTTCatalogTableオブジェクトへの定数参照を返します。 「TTCatalogTable」を参照してください。

getTable()

const TTCatalogTable & getTable(int tno)

システム内の表番号tnoに対応するTTCatalogTableへの定数参照を返します。このメソッドは、システム内のすべての表を通じて反復を容易にするためのものです。 この配列における表の順序は任意です。

次の関係が保持されることに注意してください。

0 <= tno <= getNumTables()

getUserTable()

const TTCatalogTable & getUserTable(int tno)

システム内のユーザー表番号tnoに対応するTTCatalogTableへの定数参照を返します。このメソッドは、システム内のすべてのユーザー表を通じて反復を容易にするためのものです。 この配列におけるユーザー表の順序は任意です。

次の関係が保持されることに注意してください。

0 <= tno <= getNumUserTables()

getTableIndex()

int getTableIndex(const char * owner, const char * tblname) const

このメソッドは、指定されたowner.tblnameオブジェクトに対するTTCatalogオブジェクト内の索引をフェッチします。 owner.tblnameが存在しない場合は、-2を返します。 カタログがTTCatalog::getTableIndex()をコールする前にfetchCatalogData()をコールしなかった場合は、-1を戻します。

次の例では、TTCatalogオブジェクトのTTUSER.MYDATA表に関する情報を取得します。 その後、TTCatalogTableのメソッドをコールして、この表に関する情報を取得することができます。

例4-7 カタログからの表情報の取得

TTConnection conn;
TTStatus stat;
conn.Connect(...);
TTCatalog cat (&conn);
cat.fetchCatalogData(stat);

int idx = cat.getTableIndex("TTUSER", "MYDATA");
if (idx < 0) {
  cerr << "Table TTUSER.MYDATA does not exist." << endl;
  return;
}

TTCatalogTable &table = cat.getTable(idx);

TTCatalogTable

表の列および索引に関するすべてのメタデータ情報を格納するために使用されます。

パブリック・メンバー

なし

パブリック・メソッド

メソッド	説明
getTableOwner()	表の所有者を返します。
getTableName()	表の名前を返します。
getNumColumns()	表の列数を返します。
getNumIndexes()	表の索引数を返します。
getColumn()	表のi番目の列に対応するTTCatalogColumnへの定数参照を返します。
getIndex()	表のi番目の索引に対応するTTCatalogIndexへの定数参照を返します。
isSystemTable()	表がシステム表の場合はTRUEを返します。
isUserTable()	表がユーザー表の場合はTRUEを返します。

getTableOwner()

const char * getTableOwner()

表の所有者を返します。

getTableName()

const char * getTableName()

表の名前を返します。

getNumColumns()

int getNumColumns()

表の列数を返します。

getNumIndexes()

int getNumIndexes()

表の索引数を返します。

getColumn()

const TTCatalogColumn & getColumn(int i)

表の列番号iに対応するTTCatalogColumnへの定数参照を返します。このメソッドは、システム内のすべてのユーザー表を通じて反復を容易にするためのものです。

次の関係が保持されることに注意してください。

0 <= i <= getNumColumns()

getIndex()

const TTCatalogIndex & getIndex(int i)

表の索引番号iに対応するTTCatalogIndexへの定数参照を返します。 このメソッドは、システム内のすべてのユーザー表を通じて反復を容易にするためのものです。 この配列における表の索引の順序は任意です。

次の関係が保持されることに注意してください。

0 <= i <= getNumColumns()

isSystemTable()

bool isSystemTable()

表が（SYSまたはTTREPが所有する）システム表である場合はTRUEを返します。 そうでなければ、FALSEを返します。

isUserTable()

bool isUserTable()

これがユーザー表の場合はTRUEを返します。 そうでなければ、FALSEを返します。 ユーザー表の定義は、システム表でない表であることに注意してください。 そのため、どの表の場合でも、isUserTable()はisSystemTable()と逆の値を返します。

isSystemTable()およびisUserTable()メソッドは、TTCatalog::fetchCatalogData()をコールした後、データベース内のすべての表に対して繰り返されるアプリケーションに役立ちます。 これにより、システム表とユーザー表を区別するために、表をフィルタリングしたり、注釈を付けることができます。 この実行方法の例については、TTClassesデモ・プログラムのcatalogを参照してください。

TTCatalogColumn

TTCatalogColumnクラスは、関連付けられたTTCatalogTableオブジェクトの表の単一の列に関するすべてのメタデータ情報を格納するために使用されます。

パブリック・メンバー

なし

パブリック・メソッド

メソッド	説明
getColumnName()	列の名前を返します。
getDataType()	列のODBC SQLデータ型を表す整数を返します。
getTypeName()	getDataType()によって返された型に対応するデータベース依存の名前を返します。
getNullable()	SQL_NO_NULLS、SQL_NULLABLEまたはSQL_NULLABLE_UNKNOWNを返します。
getPrecision()	列の精度を返します。
getLength()	列の長さ（バイト）を返します。
getScale()	列のスケールを返します。
getRadix()	列の基数を返します。

getColumnName()

const char * getColumnName()

列の名前を返します。

getDataType()

int getDataType()

列のデータ型を表す整数を返します。これは標準のODBC SQL型です。

getTypeName()

const char * getTypeName()

getdataType()によって返された型に対応するデータベース依存の名前を返します。

getNullable()

int getNullable()

SQL_NO_NULLS、SQL_NULLABLEまたはSQL_NULLABLE_UNKNOWNを返します。

getPrecision()

int getPrecision()

列の精度を返します。

getLength()

int getLength()

列の長さ（バイト）を返します。

getScale()

int getScale()

列のスケールを返します。

getRadix()

int getRadix()

列の基数を返します。

TTCatalogIndex

関連付けられたTTCatalogTableの索引に関するすべての情報を格納するために使用されます。

パブリック・メンバー

なし

パブリック・メソッド

メソッド	説明
getIndexName()	索引の名前を返します。
getIndexOwner()	索引の所有者を返します。
getTableName()	索引が作成された表の名前を返します。
getType()	索引の型を返します。
isUnique()	索引が一意索引かどうかを返します。
getNumColumns()	索引の列数を返します。
getColumnName()	索引の指定された列の列名を返します。
getCollation()	索引の指定された列の照合を返します。

getIndexName()

const char * getIndexName()

索引の名前を返します。

getIndexOwner()

const char * getIndexOwner()

索引の所有者を返します。

getTableName()

const char * getTableName()

索引が作成された表の名前を返します。

getType()

int getType()

索引の型を返します。TimesTenでは、許容値はPRIMARY_KEY、HASH_INDEX（PRIMARY_KEYと同じ）およびTTREE_INDEXです。その他のデータベースでは、許容値はSQL_INDEX_HASHEDおよびSQL_INDEX_CLUSTEREDです。

isUnique()

bool isUnique()

索引が一意索引かどうかを返します。 TRUEは一意であることを示し、FALSEは一意でないことを示します。

getNumColumns()

int getNumColumns()

索引の列数を返します。

getColumnName()

const char * getColumnName(int i)

索引の列番号iの列名を返します。

getCollation()

char getCollation (int i)

索引の列番号iの照合を返します。 返される値は、索引が昇順の場合はA、降順の場合はDとなります。

XLAクラス

TTClassesは、TimesTenのトランザクション・ログAPI（XLA）を使用するアプリケーションを簡単に作成できる一連のC++クラスを備えています。

XLAはコール可能なC関数のセットであり、アプリケーションはこれによってTimesTenデータ・ストア内の1つ以上の表の変更を監視できます。監視対象の表が別のアプリケーションによって変更されるたびに、XLAを使用しているアプリケーションにその変更が通知されます。 XLAの詳細は、『Oracle TimesTen In-Memory Database C開発者ガイド』のXLAおよびTimesTenのイベント管理に関する説明を参照してください。

XLAクラスでは、TimesTenでサポートされている列の最大数と同じ数のXLA列をサポートしています。 詳細は、『Oracle TimesTen In-Memory Databaseリファレンス』のシステム制限に関する説明を参照してください。

表4-5に、TTClassesのXLAクラスとその説明を示します。

表4-5 TTClassesのXLAクラス

クラス	説明
TTXlaPersistConnection	TimesTenデータ・ストアへの永続接続を定義します。
TTXlaRowViewer	特定の更新レコードから列の値をフェッチします。
TTXlaTableHandler	表の変更追跡を有効および無効にするメソッドを提供します。また、XLAからの更新通知レコードを処理するメソッドも提供します。
TTXlaTableList	TTXlaTableHandlerオブジェクトのリストを提供します。このクラスは、特定の変更を適切なメソッドにルーティングして処理するために使用されます。受信した更新通知レコードは、適切なTTXlaTableHandlerオブジェクトの適切なメソッドにルーティングされて処理されます。

TTXlaPersistConnection

TTXlaPersistConnectionは、TimesTenデータ・ストアへの永続接続を定義します。

パブリック・メンバー

なし

パブリック・メソッド

メソッド	説明
Connect()	指定されたブックマークを使用して接続します。
Connect()	指定されたブックマークを使用して接続します。ブックマークが存在しない場合は、ブックマークを作成します。
DeleteBookmarkAndDisconnect()	ブックマークを削除し、データ・ストアから切断します。
Disconnect()	TimesTenデータ・ストアへのXLA接続を閉じます。
ackUpdates()	ブックマークを次の更新セットに進めます。
getBookmarkIndex()	トランザクション・ログ内での現在の位置を格納します。
setBookmarkIndex()	保存されたトランザクション・ログ索引に戻ります。
fetchUpdatesWait()	指定された待機時間内にトランザクション・ログの更新をフェッチします。

Connect()

virtual void Connect(const char* connStr, const char * bookmark,
                     bool createBookmark, TTStatus&);

各永続XLA接続には、接続の切断時と再接続時にトランザクション・ログ内の同じ位置を検出できるように、名前（またはbookmark）が関連付けられます。 接続のブックマークの名前は、bookmarkパラメータによって指定されます。

注意: 特定のブックマーク名で接続できるXLA接続は1つのみです。 複数の接続が同じブックマークに接続しようとすると、エラーが返されます。

これが新しいブックマークであるか、以前に作成されたブックマークであるかは、ブール値のパラメータcreateBookmarkによって指定されます。 新規（createBookmark==true）として指定したブックマークがすでに存在する場合は、エラーが返されます。 同様に、既存（createBookmark==false）として指定したブックマークがまだ存在していない場合にも、エラーが返されます。

Connect()

virtual void Connect(const char* connStr, const char * bookmark, TTStatus&);

この第2のConnectメソッドでは、まず指定されたブックマークを使用して接続が試行され、それを再利用して（暗黙値としてcreateBookmark==false）接続が試行されます。 そのブックマークが存在しない場合は、接続およびbookmarkという名前の新規ブックマークの作成（暗黙値としてcreateBookmark==true）が試行されます。

このメソッドは、XLAブックマークが存在するかどうかを開発者が気にかけたくない場合に備えて、XLA接続ロジックを簡略化するために便宜上提供されているものです。

DeleteBookmarkAndDisconnect()

void DeleteBookmarkAndDisconnect(TTStatus&)

このメソッドでは、現在接続に関連付けられているブックマークが削除され、そのブックマークに関連するレコードがデータ・ストア内に保持されなくなります。その後、データ・ストアから切断されます。

Disconnect()

virtual void Disconnect(TTStatus&)

このメソッドにより、TimesTenデータ・ストアとのXLA接続が閉じます。このメソッドをコールした後も、XLAブックマークは存続します。 ブックマークを削除してデータ・ストアから切断する場合は、かわりにDeleteBookmarkAndDisconnect()（前述の説明を参照）を使用します。

ackUpdates()

void ackUpdates(TTStatus &)

このメソッドは、ブックマークを次の更新セットに進めるために使用されます。更新セットを確認した後、それらの更新を再度表示することはできません。 更新セットの再生については、後述のgetBookMarkIndex()およびsetBookMarkIndex()の説明を参照してください。

アプリケーションは、XLAレコードのバッチが読み取られて処理されたら、トランザクション・ログ・ファイルが格納されるディスクがこれらのファイルで一杯にならないように、更新を確認する必要があります。 ackUpdates()は相対的に負荷の高い操作であるため、これを頻繁にコールしないでください。

アプリケーションがXLAを使用してレコードのバッチを読み取った後に障害が発生した場合は、アプリケーションがXLAを使用して再接続したときに、それらのレコードを取得できます。

getBookmarkIndex()

void getBookmarkIndex(TTStatus &)

このメソッドでは、現在のブックマークの位置が取得されます。

setBookmarkIndex()

void setBookmarkIndex(TTStatus &)

このメソッドでは、以前に取得されたブックマークの位置にブックマークがリストアされます。このメソッドを使用すると、何度でもレコードのバッチを再生できます。

ackUpdates()がコールされると、格納されているトランザクション・ログ・プレースホルダが無効になることに注意してください。 ackUpdates()の後でsetBookmarkIndex()がコールされても、以前に取得されたブックマークの位置まで戻ることができないため、エラーが返されます。

fetchUpdatesWait()

void fetchUpdatesWait(ttXlaUpdateDesc_t*** arry, int maxrecs,
                      int* recsP, int seconds, TTStatus&)

このメソッドは、データ・ストアの変更を記述したレコードのセットをフェッチするために、XLAアプリケーションで使用されます。 ttXlaUpdateDesc_t構造体のリストが返されます。フェッチされるXLA更新がない場合、このメソッドは指定された秒数待機してから返されます。

コール元は、受信するレコードの最大数を指定します。メソッドが返されると、コール元は実際に返されたレコードの数と、変更を定義している構造体を指すポインタの配列を受信します。

このメソッドによって返されるttXlaUpdateDesc_t構造体は、XLA仕様で定義されます。これらのメソッドのC++オブジェクト指向カプセル化は提供されません。

使用方法

永続XLAアプリケーションは、複数のTTXlaPersistConnectionオブジェクトを作成する場合があります。 各TTXlaPersistConnectionオブジェクトを、独自のブックマークに関連付ける必要があります。 ブックマークは接続時に指定され、ackUpdates()およびdeleteBookmark()メソッドによって保持される必要があります。

永続XLA接続が確立されると、アプリケーションは、その終了までfetchUpdatesWait()メソッドを繰り返しコールするループに入ります。このループでは、トランザクション・ログでディスクが一杯にならないように、できるだけ速くXLAから更新をフェッチする必要があります。 アプリケーションは、更新のバッチを処理した後、それらの更新を確認するためにackUpdates()をコールし、次のfetchUpdatesWait()のコールに備えます。 更新のバッチは、setBookmarkIndex()およびgetBookmarkIndex()メソッドを使用して再生できます。 また、永続XLAアプリケーションがfetchUpdatesWait()の後（ただしackUpdates()の前）に切断されると、fetchUpdatesWait()をコールする次の接続（同じブックマーク名を使用）は、同じ更新のバッチを参照します。

TTXlaPersistConnectionオブジェクトがデータ・ストアから切断されている間に実行された更新は失われませんが、別のTTXlaPersistConnectionオブジェクトが同じブックマーク名で接続されるまで、トランザクション・ログに格納されます。

TTXlaRowViewer

TTXlaRowViewerクラスは、アプリケーション開発者がXLA変更通知レコードの構造を調べ、新旧の列値をフェッチできる強力なクラスです。

行を調べるには、TTXlaRowViewerオブジェクトを表（setTable()メソッドを介して）および行（setTuple()メソッドを介して）に関連付ける必要があります。 表は事前に定義されたTTXlaTableオブジェクトです。 行は、TTXlaPersistConnection::fetchUpdateWait()メソッドを介してXLAによって返されるttXlaUpdateDesc_t構造体の一部です。

パブリック・メンバー

なし

パブリック・メソッド

メソッド	説明
setTable()	TTXlaRowViewerを指定された表に関連付けます。
setTuple()	TTXlaRowViewerオブジェクトを指定された行イメージに関連付けます。
isNull()	行イメージ内の指定された列がNULLであるかどうかを示します。
Get()	行イメージ内の指定された列の値をフェッチします。

setTable()

void setTable(TTXlaTable*)

このTTXlaRowViewerを特定の表に関連付けます。

setTuple()

void setTuple(ttXlaUpdateDesc_t*, int whichTuple)

このTTXlaRowViewerオブジェクトを特定の行イメージに関連付けます。

TTXlaPersistConnection::fetchUpdatesWait()によって返されるttXlaUpdateDesc_t構造体に含まれる行の数は、0（ゼロ）、1または2です。

• 表に挿入された行を定義する構造体には、挿入された行の行イメージが含まれます。

• 表から削除された行を定義する構造体には、削除された行の行イメージが含まれます。

• 表内で更新された行を定義する構造体には、更新前の行イメージと更新後の行イメージが含まれます。

• 表またはデータ・ストアの他の変更を定義する構造体には、行イメージが含まれません。たとえば、索引が削除されたことをレポートする構造体には行イメージが含まれません。

setTuple()メソッドは2つの引数を受け入れます。

• データベース変更を定義する特定のttXlaUpdateDesc_t構造体へのポインタ。

• 更新構造体内のどの行イメージを調べるかを指定する整数。このパラメータの値は次のとおりです。

  • INSERTED_TUP: 新しく挿入された行を調べます。

  • DELETED_TUP: 削除された行を調べます。

  • UPDATE_OLD_TUP: 更新前の行を調べます。

  • UPDATE_NEW_TUP: 更新後の行を調べます。

setTable()およびsetTuple()メソッドがコールされた後、次のメソッドを使用して、更新レコードの行イメージに関する情報をフェッチできます。

isNull()

bool isNull(int whichCol)

行イメージ内の特定の列がNULLである（TRUEを返す）かNULLでない（FALSEを返す）かを示します。

whichColパラメータは、問い合せる列の列番号です。

Get()

void Get(int col, ...)

行イメージ内の特定の列の値をフェッチします。

これらのメソッドはTTCmd::getColumn()メソッドによく似ています。

colパラメータは、問い合せる列の列番号です。

表4-6に、サポートされるSQLデータ型と、各パラメータ型での使用に適したGetのバージョンを示します。NUMBERデータ型のバージョンは6つ、FLOATデータ型のバージョンは2つあります。格納されるデータの種類に従って、アプリケーションを設計します。 たとえば、データ型NUMBER(9,0)には、Get(int, int*)メソッドによって、データを損失することなくアクセスできます。

注意: この表では、長さlenの単位はバイトです。

表4-6 サポートされるデータ型に対するTTXlaRowViewer::Get()のバージョン

XLAデータ型	データベース・データ型	Getのバージョン
TTXLA_CHAR_TT	TT_CHAR	Get(int, char**)
TTXLA_NCHAR_TT	TT_NCHAR	Get(int, SQLWCHAR**, int* len)
TTXLA_VARCHAR_TT	TT_VARCHAR	Get(int, char**)
TTXLA_NVARCHAR_TT	TT_NVARCHAR	Get(int, SQLWCHAR**, int* len)
TTXLA_TINYINT	TT_TINYINT	Get(int, unsigned char*)
TTXLA_SMALLINT	TT_SMALLINT	Get(int, short*)
TTXLA_INTEGER	TT_INTEGER	Get(int, int*)
TTXLA_BIGINT	TT_BIGINT	Get(int, SQLBIGINT*)
TTXLA_BINARY_FLOAT	BINARY_FLOAT	Get(int, float*)
TTXLA_BINARY_DOUBLE	BINARY_DOUBLE	Get(int, double*)
TTXLA_DECIMAL_TT	TT_DECIMAL	Get(int, char**)
TTXLA_TIME	TT_TIME	Get(int, TIME_STRUCT*)
TTXLA_DATE_TT	TT_DATE	Get(int, DATE_STRUCT*)
TTXLA_TIMESTAMP_TT	TT_TIMESTAMP	Get(int, TIMESTAMP_STRUCT*)
TTXLA_BINARY	BINARY	Get(int, const void**, int* len)
TTXLA_VARBINARY	VARBINARY	Get(int, const void**, int* len)
TTXLA_NUMBER	NUMBER	Get(int, double*) Get(int, char**) Get(int, char*) Get(int, short*) Get(int, int*) Get(int, SQLBIGINT*)
TTXLA_DATE	DATE	Get(int, TIMESTAMP_STRUCT*)
TTXLA_TIMESTAMP	TIMESTAMP	Get(int, TIMESTAMP_STRUCT*)
TTXLA_CHAR	CHAR	Get(int, char**)
TTXLA_NCHAR	NCHAR	Get(int, SQLWCHAR**, int* len)
TTXLA_VARCHAR	VARCHAR2	Get(int, char**)
TTXLA_NVARCHAR	NVARCHAR2	Get(int, SQLWCHAR**, int* len)
TTXLA_FLOAT	FLOAT	Get(int, double*) Get(int, char**)

使用方法

変更通知レコードに含まれる行イメージから列値をフェッチするために使用されます。

TTXlaTableHandler

TTXlaTableHandlerクラスは、アプリケーション開発者が特定の表の変更を処理するカスタマイズ済クラスを記述する際の基本クラスです。

コンストラクタは、TTXlaTableHandlerを特定の表に関連付け、このオブジェクトに含まれるTTXlaTableオブジェクトを初期化します。

TTXlaTableHandler(TTXlaConnection& conn, const char* ownerP, const char* nameP)

（TTXlaTableに関する「内部クラス」を参照してください。）

パブリック・メンバー

なし

保護メンバー

メンバー	説明
TTXlaTable tbl;	処理対象の表に関連付けられたオブジェクト。
TTXlaRowViewer row;	挿入または削除される行、あるいは変更される行の古いイメージを表示するために使用されます。
TTXlaRowViewer row2;	更新される行の新しいイメージを表示するために使用されます。

パブリック・メソッド

メソッド	説明
EnableTracking()	基礎となる表のXLA更新追跡を有効にします。
DisableTracking()	基礎となる表のXLA更新追跡を無効にします。
HandleChange()	ttXlaUpdateDesc_tからレコードを適切な処理ルーチンにディスパッチして処理します。
HandleDelete()	削除操作を処理するためにHandleChange()メソッドがコールされると起動されます。
HandleInsert()	挿入操作を処理するためにHandleChange()メソッドがコールされると起動されます。
HandleUpdate()	更新操作を処理するためにHandleChange()メソッドがコールされると起動されます。
generateSQL()	特定のXLAレコードに関連付けられたSQLを返します。

EnableTracking()

virtual void EnableTracking(TTStatus&);

基礎となる表のXLA更新追跡を有効にします。このメソッドがコールされるまでは、XLAによってこの表の変更に関する情報が返されません。

DisableTracking()

virtual void DisableTracking(TTStatus&);

基礎となる表のXLA更新追跡を無効にします。このメソッドがコールされた後は、XLAによってこの表の変更に関する情報が返されません。

HandleChange()

virtual void HandleChange(ttXlaUpdateDesc_t*, void* pData = 0);

ttXlaUpdateDesc_tを適切な処理ルーチンにディスパッチして処理します。更新記述が分析され、それが削除、挿入または更新のいずれであるかが判別されます。 その後、適切な仮想メソッド（HandleDelete()、HandleInsert()またはHandleUpdate()）がコールされます。

pDataパラメータの使用例は、「トランザクション境界におけるXLA更新の確認」を参照してください。

HandleDelete()

virtual void HandleDelete(ttXlaUpdateDesc_t*) = 0;

このメソッドは、削除操作を処理するためにHandleChange()メソッドがコールされるたびに起動されます。

このメソッドはTTXlaTableHandler基本クラスには実装されませんが、このクラスから導出される任意のクラスで提供される必要があります。アプリケーション開発者は、削除される行を処理するロジックをこのメソッドに配置する必要があります。

表から削除された行は、rowという名前のRowViewerによって取得できます。

HandleInsert()

virtual void HandleInsert(ttXlaUpdateDesc_t*) = 0;

このメソッドは、挿入操作を処理するためにHandleChange()メソッドがコールされるたびに起動されます。

このメソッドはTTXlaTableHandler基本クラスには実装されませんが、このクラスから導出される任意のクラスで提供される必要があります。アプリケーション開発者は、挿入される行を処理するロジックをこのメソッドに配置する必要があります。

表から挿入された行は、rowという名前のRowViewerによって取得できます。

HandleUpdate()

virtual void HandleUpdate(ttXlaUpdateDesc_t*) = 0;

このメソッドは、更新操作を処理するためにHandleChange()メソッドがコールされるたびに起動されます。

このメソッドはTTXlaTableHandler基本クラスには実装されませんが、このクラスから導出される任意のクラスで提供される必要があります。アプリケーション開発者は、更新される行を処理するロジックをこのメソッドに配置する必要があります。

表で更新された行の以前のバージョンはrowという名前のRowViewerオブジェクトによって取得でき、行の新しいバージョンはrow2という名前のRowViewerオブジェクトによって取得できます。

generateSQL()

void generateSQL (ttXlaUpdateDesc_t*, char * buffer,
                  SQLINTEGER maxLen, SQLINTEGER *actualLen, TTStatus &);

このメソッドを使用して、特定のXLAレコードに関連付けられたSQLを出力できます。 SQL文字列はbufferパラメータによって返されます。 このパラメータは、このメソッドのコール元が領域を割り当て、maxLenパラメータで長さを指定したパラメータです。 actualLenパラメータは、返されるSQL文字列の実際の長さに関する情報を返します。 長さの単位はバイトです。

生成されたSQL文字列よりmaxLenが小さい場合は、TTStatusエラーが返され、バッファの内容とactualLenは変更されません。

使用方法

アプリケーション開発者は、TTXlaTableHandlerから1つ以上のクラスを導出し、そのクラスのHandleInsert()、HandleDelete()およびHandleUpdate()メソッドに、アプリケーションのロジックの大部分を配置できます。

1つの方法は、各表につき1つずつ、TTXlaTableHandlerから複数のクラスを導出することです。 たとえば、顧客の変更を処理するビジネス・ロジックをCustomerTableHandlerクラスに実装し、注文の変更を処理するビジネス・ロジックをOrderTableHandlerクラスに実装します。

もう1つの方法は、様々な使用例を処理する1つ以上の汎用クラスをTTXlaTableHandlerから導出することです。 たとえば、TTXlaTableHandlerから導出した汎用クラスを使用して、公開/サブスクライブ・システムを介して変更をパブリッシュできます。

TTXlaTableList

TTXlaTableListクラスは、更新通知イベントを適切なTTXlaTableHandlerにディスパッチするために使用されます。 このクラスでTableHandlerオブジェクトのリストが保守されます。 更新通知がXLAから受信されると、適切なTableHandlerの適切なHandleメソッドがコールされ、各レコードを処理します。

たとえば、CustomerTableHandler型のオブジェクトが表CUSTOMERの変更を処理し、OrderTableHandler型のオブジェクトが表ORDERSの変更を処理する場合、アプリケーションでは両方のオブジェクトをTTXlaTableListに含める必要があります。 XLA更新通知レコードがXLAからフェッチされたとき、TTXlaTableList::HandleChange()をコールするだけで、それらのレコードを適切なハンドラにディスパッチできます。

コンストラクタには2種類の形式があります。

TTXlaTableList(TTXlaConnection *, unsigned int i)

iは、監視するデータベース・オブジェクトの数です。

または

TTXlaTableList(TTXlaConnection* cP);

cPは、XLA操作に使用するデータベース接続を示します。この形式のコンストラクタでは、最大150のデータベース・オブジェクトを監視できます。

パブリック・メンバー

なし

パブリック・メソッド

メソッド	説明
add()	リストにTableHandlerを追加します。
del()	リストからTableHandlerを削除します。
HandleChange()	ttXlaUpdateDesc_tから取得されたレコードを処理します。

add()

void add(TTXlaTableHandler* h);

リストにTableHandlerを追加します。

del()

void del(TTXlaTableHandler* h);

リストからTableHandlerを削除します。

HandleChange()

void HandleChange(ttXlaUpdateDesc_t* p, TTStatus&);

XLAからttXlaUpdateDesc_tを受信したとき、このメソッドをコールしてそれを処理できます。 このメソッドは、レコードが参照する表を特定し、適切なTableHandlerのHandleChange()メソッドをコールします。

使用方法

TableHandlerオブジェクトをTableListに登録すると、XLAから更新通知レコードをフェッチし、適切なメソッドにディスパッチして処理するプロセスを、非常に簡単なループによって実行できます。

内部クラス

これらのクラスは、C++クラス・ライブラリで提供され、他のクラスで内部的に使用されます。これらの実装は変更されることがあります。

• TTCommand: TTCmdの基本クラスであるTTCommandクラスは、ODBC文（SQLHSTMT）およびODBC関数コールへの低レベルのC++マッピングを提供します。

• TTParameter: TTCmdは、TTParameterクラスを介して自己定義パラメータを実装します。

• TTColumn: TTCmdは、TTColumnクラスを介して自己定義列を実装します。

• TTXlaTable: TTXlaTableオブジェクトは、変更の有無が監視されている表についての情報を定義します。

• TTXlaColumn: TTXlaRowViewerは、この関数を使用して、表内の1つの列を定義します。