TTClassesクラスの使用

この項では、TTClassesライブラリの各クラスの使用方法についての追加情報を示します。

• 一般的に使用されるクラスの使用方法

• システム・カタログ・クラスの使用方法

• XLAクラスの使用方法

一般的に使用されるクラスの使用方法

この項では、TTClassesライブラリで一般的に使用されるクラスについて、それぞれの使用方法を説明します。

• TTCGlobalの使用方法

• TTCStatusの使用方法

• TTConnectionの使用方法

• TTConnectionPoolの使用方法

• TTCmdの使用方法

TTCGlobalの使用方法

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

このロギング機能は、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ロギングの使用およびTTGlobalリファレンスを参照してください。

TTCStatusの使用方法

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

エラーまたは警告が発生するとTTStatusオブジェクトが例外としてスローされます。これによって、C++アプリケーションで{try/catch}ブロックによる障害の検出とリカバリが可能となります。

...
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には、TTErrorとTTWarningの2つのサブクラスがあります。ODBC警告(たとえば、RETURN RECEIPT警告)は、通常ODBCエラーほど重大ではないので、一般的は別のロジックを使用して処理する必要があります。ODBCエラーは、プログラムを記述して処理する必要があります。プログラムによるODBC警告の処理が保証される場合もありますが、通常は単純にログに記録するだけで十分です。

この例では、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
}

ノート:

TimesTenではほとんどの一時エラーが自動的に解決されますが(これはTimesTen Scaleoutでは特に重要)、odbc_error属性をとおしてアプリケーションによって検出されたエラーがTT005のSQL状態を示している場合は、現在のトランザクションを再試行することをお薦めします。Oracle TimesTen In-Memory Database C開発者ガイドの一時エラー(ODBC)を参照してください。

TTStatusリファレンスも参照してください。

TTConnectionの使用方法

TTConnectionクラスは、データベースに対する接続という概念をカプセル化します。TTConnectionは、ODBC接続ハンドル(SQLHDBC)の付加価値C++ラッパーと考えることができます。TimesTenを使用するすべてのアプリケーションは、1つ以上のTTConnectionオブジェクトを作成する必要があります。

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

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

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

TimesTen接続は、親プロセスから継承できません。プロセスが、子プロセスを作成する(分岐)前にデータベース接続を開いた場合、子が同じ接続を使用することはできません。子が親のデータベース接続を使用しようとすると、アプリケーションが失敗したりコア・ダンプが発生する場合があります。

接続および切断は、比較的負荷の高い操作であるため、アプリケーションでは頻繁にデータベース接続を行ったり、切断しないようにする必要があります。また、短期間の接続では準備済文のメリットがなくなります。そのかわりに、アプリケーション・プロセスの開始時にデータベース接続を確立し、そのプロセスの存続中はそれを再利用します。

ヒント:

基礎となるODBC接続オブジェクトを直接操作する必要がある場合は、TTConnection::getHdbc()メソッドを使用します。

データベースに接続する権限は、CREATE SESSION権限を使用して、直接またはPUBLICロールを介してユーザーに付与する必要があります。接続メソッドを参照してください。

TTCmd、TTConnectionおよびTTConnectionPoolの使用およびTTConnectionリファレンスも参照してください。

TTConnectionPoolの使用方法

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()メソッドを使用し、アイドル状態の接続を取得および返します。

ヒント:

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)

その後、適切な対応するConnectAll()メソッドを使用します。

データベースに接続する権限は、CREATE SESSION権限を使用して、直接またはPUBLICロールを介してユーザーに付与する必要があります。接続メソッドを参照してください。

TTCmd、TTConnectionおよびTTConnectionPoolの使用およびTTConnectionPoolリファレンスも参照してください

TTCmdの使用方法

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メソッドは、ODBCドライバ・マネージャとともに使用するとエラーを返します。詳細は、ODBCドライバ・マネージャ使用時の考慮事項(Windows)を参照してください。

• 基礎となるODBC文を直接操作する必要がある場合は、TTCmd::getHandle()メソッドを使用してください。

TTCmd、TTConnectionおよびTTConnectionPoolの使用およびTTCmdリファレンスも参照してください。

システム・カタログ・クラスの使用方法

この項では、TTClassesシステム・カタログ・クラスについて、それぞれの使用方法を説明します。

• TTCatalogの使用方法

• TTCatalogTableの使用方法

• TTCatalogColumnの使用方法

• TTCatalogIndexの使用方法

• TTCatalogSpecialColumnの使用方法

TTCatalogの使用方法

TTCatalogクラスは、データベース内の表に関するメタデータ情報へのプログラム的なアクセスに使用される、トップ・レベルのクラスです。このクラスを使用すると、システム・カタログからのメタデータの読取りが容易になります。TTCatalogオブジェクトのデータが構造には、読み取られた情報が含まれます。

TTCatalogオブジェクトを使用するには、そのオブジェクトのfetchCatalogData()メソッドをコールします。fetchCatalogData()メソッドは、データベース接続を使用するTTCatalogの唯一のメソッドです。その他のメソッドは、単純にfetchCatalogData()から取得したデータを返します。

TTCatalogオブジェクトの内部には、TTCatalogTableオブジェクトの配列があります。クラス・コンストラクタを除くTTCatalogのすべてのパブリック・メソッドを使用して、そのTTCatalogTable配列への読取り専用アクセスを取得します。

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

TTCatalog (TTConnection* conn)

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

• SQLTables()

• SQLColumns()

• SQLSpecialColumns()

• SQLStatistics()

TTCatalogリファレンスも参照してください。

TTCatalogTableの使用方法

最上位レベルのTTCatalogクラスの各オブジェクト内には、TTCatalogTableオブジェクトの配列が含まれます。

TTCatalogTableオブジェクトはTTCatalog::getTable()メソッドを使用して取得され、表の列および索引に関するメタデータ情報がすべて格納されます。

各TTCatalogTableオブジェクトには、TTCatalogColumnオブジェクトの配列と、TTCatalogIndexオブジェクトの配列が含まれます。

TTCatalogTableリファレンスも参照してください・

TTCatalogColumnの使用方法

各TTCatalogTableオブジェクトには、TTCatalogColumnオブジェクトの配列と、TTCatalogIndexオブジェクトの配列が含まれます。

TTCatalogColumnクラスは、表の1つの行のすべてのメタデータ情報を格納するために使用されます。この表はTTCatalogTableオブジェクトで表現され、このオブジェクトからTTCatalogTable::getColumn()コールを使用して列が取得されています。

TTCatalogColumnリファレンスも参照してください。

TTCatalogIndexの使用方法

各TTCatalogTableオブジェクトには、TTCatalogColumnオブジェクトの配列と、TTCatalogIndexオブジェクトの配列が含まれます。

TTCatalogIndexクラスは、表の索引のメタデータ情報を保存するために使用されます。この表は、TTCatalogTableオブジェクトで表現され、このオブジェクトからTTCatalogTable::getIndex()コールを使用して索引が取得されています。

TTCatalogIndexリファレンスも参照してください。

TTCatalogSpecialColumnの使用方法

該当するTTCatalogTableオブジェクトでgetSpecialColumn()メソッドをコールし、TTCatalogSpecialColumnオブジェクトを取得します。

TimesTenで唯一サポートされる特殊列は、ROWID疑似列なので、TTCatalogSpecialColumnオブジェクトにはROWIDの情報しか含めることができません。

TTCatalogSpecialColumnリファレンスも参照してください。

XLAクラスの使用方法

この項では、TTClassesのXLAクラスについて概要を示し、それぞれの使用方法を説明します。

• XLAクラスについて

• TTXlaPersistConnectionの使用方法

• TTXlaRowViewerの使用方法

• TTXlaTableHandlerの使用方法

• TTXlaTableListの使用方法

• TTXlaTableの使用方法

• TTXlaColumnの使用方法

XLAクラスについて

TTClassesは、TimesTen ClassicでサポートされているTimesTenのトランザクション・ログAPI(XLA)で使用する、アプリケーション用の一連のクラスを備えています。

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

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

ノート:

ODBCドライバ・マネージャ使用時の考慮事項(Windows)に示したように、汎用ODBCドライバ・マネージャを使用するときには、TTClassesではXLA機能がサポートされません。

TTXlaPersistConnectionの使用方法

データベースへのXLA接続を作成するには、TTXlaPersistConnectionを使用します。

XLAアプリケーションでは、必要に応じて複数のTTXlaPersistConnectionオブジェクトを作成できます。各TTXlaPersistConnectionオブジェクトには、接続時に指定する、ackUpdates()メソッドとdeleteBookmarkAndDisconnect()メソッドで維持する独自のブックマークと関連付ける必要があります。多くのアプリケーションでは、XLAブックマークは1つまたは2つのみ必要です。

XLA接続の確立後、アプリケーションは、その終了までfetchUpdatesWait()メソッドを繰り返しコールするループに入ります。このループでは、トランザクション・ログで使用可能なファイル・システム領域が一杯にならないように、できるだけ速くXLAから更新をフェッチする必要があります。

ノート:

• トランザクション・ログは、指定している場合、TimesTen LogDir属性で設定したファイル・システムの場所にあり、LogDirを指定していない場合はDataStore属性で設定した場所にあります。Oracle TimesTen In-Memory Databaseリファレンスのデータ・ストア属性を参照してください。

• 各ブックマークは、トランザクション・ログに独自のログの保持を確立します。(Oracle TimesTen In-Memory DatabaseリファレンスのttLogHoldsを参照してください。)定期的に進められないブックマークがある場合、チェックポイント処理ではトランザクション・ログをパージできません。これによって、時間の経過とともにファイル・システムが一杯になる場合があります。

アプリケーションは、更新のバッチを処理した後、それらの更新を確認するためにackUpdates()をコールし、次のfetchUpdatesWait()のコールに備えます。更新のバッチは、setBookmarkIndex()およびgetBookmarkIndex()メソッドを使用して再生できます。また、XLAアプリケーションがfetchUpdatesWait()の後(ただしackUpdates()の前)に切断されると、fetchUpdatesWait()をコールする次の接続(同じブックマーク名を使用)は、同じ更新のバッチを参照します。

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

データベースに接続する権限は、CREATE SESSION権限を使用して、直接またはPUBLICロールを介してユーザーに付与する必要があります。接続メソッドを参照してください。これに加え、XLA接続と機能にはXLA権限が必要です。

TTXlaPersistConnectionリファレンスも参照してください。

TTXlaRowViewerの使用方法

変更通知レコードからの行イメージを表すTTXlaRowViewerを使用すると、XLA変更通知レコードの構造と新旧の列値を検証できます。

このクラスのメソッドは、変更通知レコード内の行イメージから列値を検証するために使用できます。TTXlaTableクラスの関連情報(TTXlaTableの使用方法)も参照してください。

行を検証する前に、TTXlaRowViewerオブジェクトはTTXlaTableHandler::HandleInsert()、HandleUpdate()またはHandleDelete()メソッド、またはユーザー記述のオーバーロード・メソッド内で起動されるsetTuple()メソッドを使用する行と関連付ける必要があります。isNull()メソッドを使用すると、列にnull値があるかを確認できます。nullではない列値は適切なオーバーロードされるGet()メソッドを使用して検査できます。

TTXlaRowViewerリファレンスも参照してください。

TTXlaTableHandlerの使用方法

TTXlaTableHandlerクラスは、表の変更追跡を有効および無効にするメソッドを提供します。また、XLAからの更新通知レコードを処理するメソッドも提供します。

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

コンストラクタは、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 Classicのクイック・スタートのxlasubscriber1とxlasubscriber2のデモを参照してください。(TimesTenクイック・スタートおよびサンプル・アプリケーションについてを参照してください。)

TTXlaTableHandlerリファレンスも参照してください。

TTXlaTableListの使用方法

TTXlaTableListクラスには、一連のTTXlaTableHandlerオブジェクトがあり、更新通知イベントを適切なTTXlaTableHandlerにディスパッチするために使用されます。

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

XLAからの更新通知を受信すると、そのレコードを処理するための適切なTTXlaTableHandlerオブジェクトの適切なHandleXxx()メソッドがコールされます。

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

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

TTXlaTableList(TTXlaPersistConnection* cP, unsigned int num_tbls_to_monitor)

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

または

TTXlaTableList(TTXlaPersistConnection* cP);

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

TTXlaTableListリファレンスも参照してください。

TTXlaTableの使用方法

TTXlaTableクラスは、変更の監視対象の表のメタデータをカプセル化します。

TTXlaTableは、TimesTen ttXlaTblDesc_t Cデータ構造のメタデータ・インタフェースとして動作します。(Oracle TimesTen In-Memory Database C開発者ガイドのttXlaTblDesc_tを参照してください。)

ユーザー・アプリケーションでTTXlaTableHandlerを拡張するクラスが作成される場合、通常、列名をそのXLA列番号とマップするためにTTXlaTable::getColNumber()がコールされます。この列番号は、その後TTXlaRowViewer::Get()メソッドへの入力に使用できます。これは、TimesTen Classicのクイック・スタートのxlasubscriber2のデモで示されています。(TimesTenクイック・スタートおよびサンプル・アプリケーションについてを参照してください。)

このクラスには、表の名前、所有者、列数を返す便利なメタデータ関数もあります。

TTXlaTableリファレンスも参照してください。

TTXlaColumnの使用方法

TTXlaColumnオブジェクトには、変更の監視対象の表の単一行のメタデータが含まれます。

TTXlaColumnは、TimesTen ttXlaColDesc_t Cデータ構造のメタデータ・インタフェースとして動作します。(Oracle TimesTen In-Memory Database C開発者ガイドのttXlaColDesc_tを参照してください。)列名、型、精度、スケールを含む情報を取得できます。

アプリケーションで、TTXlaRowViewer::getColumn()メソッドを使用し、列とTTXlaColumnオブジェクトを関連付けます。

TTXlaColumnリファレンスも参照してください。