3 TimesTenでのOracle Call Interfaceのサポート

Oracle TimesTen In-Memory DatabaseおよびOracle In-Memory Database Cache（IMDB Cache）では、Oracle Call Interface（OCI）がサポートされます。

この章の内容は次のとおりです。

• OCIの概要

• TimesTen OCIサポートの概要

• TimesTen OCIの使用

• TimesTen OCIのその他の機能

• コール、ハンドル、記述子、SQLデータ型およびパラメータ属性のサポート

この章では、OCIサポートに関するTimesTen固有の情報に焦点を当てます。 詳細は、Oracle Databaseライブラリの『Oracle Call Interface Programmer's Guide』を参照してください。

OCIの概要

OCIとは、データベース・サーバーにアクセスしてSQL実行を制御するために使用可能な機能を備えたAPIのことです。OCIでは、CおよびC++プログラミング言語のデータ型、コール規則、構文およびセマンティックがサポートされています。すべてのCまたはC++プログラムと同様にOCIプログラムをコンパイルおよびリンクします。前処理またはプリコンパイルの手順はありません。

データベース・アクセスおよび検索機能のOCIライブラリは、実行時にアプリケーションにリンクできる動的なランタイム・ライブラリの形式になっています。 OCIライブラリには、次の機能領域が含まれます。

• SQLアクセス機能

• データ型マッピングおよび操作機能

• CコールバックをPL/SQLに書き込むための外部プロシージャ機能

次に、OCIに用意されている、またはOCIでサポートされている多数の役立つ機能の一部を示します。

• 文のキャッシュ

• 動的SQL

• トランザクション制御文、セッション制御文およびシステム制御文（DML文のような）を処理する機能

• サーバー・メタデータのレイヤーを公開する記述機能

• コミット・リクエストを文の実行と関連付けてラウンドトリップを減らす機能

• ラウンドトリップを減らす透過的プリフェッチ・バッファを使用した問合せの最適化

• OCIハンドルの相互排他ロックを不要にするスレッド・セーフティ

OCIの一般的な詳細は、Oracle Databaseドキュメント・セットに含まれている『Oracle Call Interface Programmer's Guide』を参照してください。

TimesTen OCIサポートの概要

この章では、TimesTenおよびIMDB CacheでのOCIの使用に固有の情報を示します。 TimesTen OCIの構文および使用方法は、Oracle Databaseの構文および使用方法と同じです。

この項の内容は次のとおりです。

• OCIのライブラリおよびアーキテクチャ

• グローバリゼーション・サポート

• TimesTenの制限

• ttSrcScanユーティリティ

OCIのライブラリおよびアーキテクチャ

TimesTen OCIは、Oracleクライアント・ライブラリおよびTimesTen ODBCライブラリに依存します。 TimesTen OCIサポートにより、多くの既存のOCIアプリケーションをTimesTenでダイレクト・モードまたはクライアント/サーバー・モードで実行できます。 また、OCIをデータベース・インタフェースとして使用するPro*C/C++などのその他のOracle製品を使用することもできます。 OCIアプリケーションからPL/SQLをコールすることもできます。 図3-1に、TimesTenアーキテクチャにおけるOCIサポートの位置付けを示します。

図3-1 TimesTenアーキテクチャにおけるOCI

図3-1「TimesTenアーキテクチャにおけるOCI」の説明

TimesTenには、OCIクライアント・ライブラリとしてOracle Instant Clientが含まれます。

TimesTenリリース11.2.1 OCIはOracleリリース11.1.0.7 OCIに基づいており、現在のOCI 8スタイルのAPIをサポートしています。 たとえば、OCIStmtExecute()関数はサポートされますが、これより古いoexec()関数はサポートされません。 Oracle Databaseドキュメントの『Oracle Call Interface Programmer's Guide』の廃止されたOCIルーチンに関する項を参照してください。

グローバリゼーション・サポート

この項では、グローバリゼーションのTimesTen OCIサポートについて説明します。

キャラクタ・セット

接続用のキャラクタ・セットを指定するには、OCIプログラムでNLS_LANG環境変数を設定するか、またはOCIEnvNlsCreate()をコールできます。 odbc.iniファイル内のすべての接続キャラクタ・セットは無視されます。 キャラクタ・セットを明示的に設定することをお薦めします。 通常、デフォルトはAMERICAN_AMERICA.US7ASCIIです。

TimesTen OCIでは言語またはロケール（地域）設定はサポートされていないため、前述のAMERICAN_AMERICAなどのNLS_LANGの言語および地域コンポーネントは無視されます。 ただし、言語およびロケールを指定しない場合にも、NLS_LANGの設定時にキャラクタ・セットの前にピリオドを含める必要があります。たとえば、AMERICAN_AMERICAは無視されますが、次の設定はいずれも有効です。

NLS_LANG=AMERICAN_AMERICA.WE8ISO8859P1

または

NLS_LANG=.WE8ISO8859P1

注意: NLS_LANG環境設定は、TimesTenのデフォルトのキャラクタ・セットよりも優先されます。 TIMESTEN8キャラクタ・セットはサポートされていません。 Windowsでは、NLS_LANG設定が環境にない場合、レジストリから取得されます。 OCIまたはPro*C/C++プログラムでTimesTenへの接続に問題が生じた場合は、HKEY_LOCAL_MACHINE\Software\ORACLE\のNLS_LANG設定が有効であり、TimesTenによってサポートされているキャラクタ・セットを指定していることを確認します （NLS_LANGレジストリ設定は、NAなどの無効な値に設定されることがあります。 値がNAの場合、TimesTenインストーラによってAMERICAN_AMERICA.US7ASCIIに置き換えられます）。 この問題は、以前にOracle9iより前のOracleバージョンがシステムにインストールされていた場合にのみ発生する場合があります。 NLS_LANGについては、『Oracle Databaseグローバリゼーション・サポート・ガイド』のNLS_LANG環境変数でのロケールの選択に関する項を参照してください。 OCIコールの詳細は、『Oracle Call Interface Programmer's Guide』のOCIEnvNlsCreate()に関する項を参照してください。

その他のグローバリゼーション機能

TimesTen OCIでは、他に、次のグローバリゼーション機能もサポートされます。 これらの機能は、環境変数またはTimesTenの一般的な接続属性として設定できます。 環境変数の設定が優先されます。

• NLS_LENGTH_SEMANTICS: デフォルトで、文字データ型CHARおよびVARCHAR2の長さは、文字数ではなくバイト数で指定します。 シングルバイト文字エンコードの場合は、バイトでの指定は正しく機能します。 マルチバイト文字・エンコードの場合は、NLS_LENGTH_SEMANTICSを使用して、かわりに文字長セマンティクスによってCHAR列およびVARCHAR2列を作成できます。 サポートされている設定は、BYTE（デフォルト）およびCHARです。 （NCHAR列およびNVARCHAR2列は、常に文字ベースです。 既存の列は影響を受けません。）

• NLS_SORT: 文字データのソートの種類を指定します。 NLS_LANGのデフォルト値よりも優先されます。 有効な値は、BINARYまたはTimesTenでサポートされているすべての言語ソート名です。 たとえば、ドイツ語の言語ソート順序を指定するには、NLS_SORT=Germanと設定します。 NLS_NCHAR_CONV_EXCP: NCHARまたはNVARCHARデータとCHARまたはVARCHAR2データの間の暗黙的または明示的なキャラクタ・タイプの変換中にデータが消失した場合に、エラーがレポートされるかどうかを指定します。 有効な設定は、TRUEおよびFALSEです。 デフォルト値はFALSEで、エラーはレポートされません。

注意: これらの環境変数は、OCIまたはPro*C/C++プログラムの対応するTimesTen接続属性よりも優先されます。

これらの環境変数および関連する機能の詳細は、『Oracle TimesTen In-Memory Databaseオペレーション・ガイド』および『Oracle Databaseグローバリゼーション・サポート・ガイド』を参照してください。

TimesTenの制限

TimesTenでは、TimesTenまたはIMDB Cacheに存在しない機能に関連するOCIコールはサポートされていません。 たとえば、TimesTenおよびIMDB Cacheでは、次のOracle Database機能はサポートされていません。

• アドバンスト・キューイング

• ANYDATA

• オブジェクトのサポート

• LOBデータ型

• コレクション

• カートリッジ・サービス

• ダイレクト・パス・ロード

• 日付/時間間隔

• イテレータ

• BFILE

• Cryptographic Toolkit

• XML DBサポート

• Spatialサービス

• イベント処理

• セッションの切替え

• スクロール可能カーソル

TimesTenおよびOracleはどちらもXAをサポートしていますが、TimesTenではOCIを介したXAのサポートは行われていません。

また、TimesTen OCIには、次の制限があります。

• TypeModeデータベース属性は、Oracleの動作に対応する0に設定する必要があります。

• DuplicateBindMode接続属性は、Oracleの動作に対応する0に設定する必要があります。

• DDLCommitBehavior接続属性は、Oracleの動作に対応する0に設定する必要があります。

• 非同期コールはサポートされていません。

• 接続プーリングおよびセッション・プーリングはサポートされていません。

• OCIDescribeAny()でのオブジェクトの記述は、名前による記述のみがサポートされます。 PL/SQLオブジェクトの記述はサポートされていません。

• TimesTenクライアント/サーバー自動クライアント・フェイルオーバーはサポートされていません。

• TNS Pingユーティリティでは、TimesTenへの接続は認識されていません。

• INSERT、UPDATEおよびDELETE文からの暗黙的ROWID値の取得はサポートされていません。

• 結果セットを返すTimesTen組込みプロシージャは、直接にはサポートされていません。

• PL/SQLブロック、プロシージャ・コールまたは関数コールから単一のREF CURSORのみが返されます。

• OCIBindArrayOfStruct()およびOCIDefineArrayOfStruct()による構造体のバインドおよび定義は、SQL文についてはサポートされていますが、PL/SQLについてはサポートされていません。

• SQL*PlusやSQL*LoaderなどのOracleユーティリティはサポートされていません。

ttSrcScanユーティリティ

既存のOCIプログラムがあり、そのプログラムでTimesTenではサポートされていないOCI機能が使用されているかどうかを確認する場合は、ttSrcScanコマンドライン・ユーティリティを使用すると、サポートされていない関数、パッケージ、型、型コード、属性、モードおよび定数に関してプログラムをスキャンできます。このユーティリティは、TimesTenまたはOracleがインストールされていない場合でも実行可能なスタンドアロン・ユーティリティであり、TimesTenでサポートされているどのプラットフォームでも動作します。入力としてソース・コード・ファイルを読み取り、出力としてHTMLおよびテキスト・ファイルを作成します。 サポートされていない項目が検出されると、それらの項目はログに記録され、代替が示されます。ttSrcScan実行可能ファイルは、TimesTenのインストール先のquickstart/sample_utilディレクトリにあります。

入力ファイルまたはスキャン対象のプログラムのディレクトリ、およびttSrcScanレポートの出力ディレクトリを指定します。その他のオプションも使用できます。詳細は、sample_utilディレクトリにあるREADMEファイルを参照してください。

TimesTen OCIの使用

この項では、TimesTen OCIアプリケーションの開始に関する次の内容について説明します。

• TimesTen OCIの環境変数

• OCIアプリケーションのコンパイルおよびリンク

• OCIからTimesTenデータ・ストアへの接続

• エラー・レポート

• OCIのデモ・プログラム

TimesTen OCIの環境変数

表3-1に、TimesTen OCIアプリケーションを実行するための環境変数を示します。 設定は、特に記述のないかぎり、ダイレクト・モードとクライアント/サーバー・モードの両方に適用されます。

環境変数は、インストール後に必要に応じて、使用オペレーティング・システムに適用可能なTimesTenのinstall_dir/bin/ttenvスクリプトまたはquickstart/ttquickstartenvスクリプトを使用して変更できます。

クイック・スタート・デモに付属のTimesTen OCIファイルおよびPro*C/C++ Makeファイルを使用して、適切な環境設定を実行することもできます。これらのファイルは次の場所にあります。

quickstart/sample_code/oci/
quickstart/sample_code/proc/

環境変数およびttenvの詳細は、『Oracle TimesTen In-Memory Databaseインストレーション・ガイド』の環境変数に関する項を参照してください。

表3-1 TimesTen OCIの環境変数

変数	必須またはオプション	設定
LD_LIBRARY_PATH（UNIX） PATH（Windows）	必須	パス内で、Oracle Instant ClientディレクトリがOracle Databaseライブラリより前になるように設定する必要があります。 パスは、install_dirの次のいずれかのスクリプトを使用すると適切に設定されます。 bin/ttenv quickstart/ttquickstartenv （ただし、クイック・スタートを別の場所にインストールしている場合を除きます。）
TNS_ADMIN	tnsnamesネーミング・メソッドを使用する場合は必須	tnsnames.oraファイルを保存するディレクトリを指定します。 これは、TimesTenがsqlnet.oraファイルを検索するディレクトリでもあります。
TWO_TASK（UNIX） LOCAL（Windows）	オプション	OCIログオン・コールでdbname引数を指定するかわりに、この環境変数（使用プラットフォームに適したほう）を使用できます。 設定は、有効なTNS名または簡易接続文字列で構成されます。 詳細は、「OCIからTimesTenデータ・ストアへの接続」を参照してください。
NLS_LANG	オプション	「キャラクタ・セット」を参照してください。 キャラクタ・セット・コンポーネントのみが有効です。TimesTenでサポートされているキャラクタ・セットを指定している必要があります。 言語および地域の値は無視されます。 この環境変数は、TimesTenのデフォルトのキャラクタ・セットよりも優先されます。
NLS_SORT	オプション	「その他のグローバリゼーション機能」を参照してください。 ソート順序は、TimesTenでサポートされている値である必要があります。 この環境変数は、TimesTenのNLS_SORT接続属性よりも優先されます。
NLS_LENGTH_SEMANTICS	オプション	「その他のグローバリゼーション機能」を参照してください。 この環境変数は、TimesTenのNLS_LENGTH_SEMANTICS接続属性よりも優先されます。
NLS_NCHAR_CONV_EXCP	オプション	「その他のグローバリゼーション機能」を参照してください。 この環境変数は、TimesTenのNLS_NCHAR_CONV_EXCP接続属性よりも優先されます。

注意: TimesTenの接続属性については、『Oracle TimesTen In-Memory Databaseリファレンス』のデータ・ストア属性に関する項を参照してください。

OCIアプリケーションのコンパイルおよびリンク

TimesTenでOCIアプリケーションをコンパイルおよびリンクする手順を変更する必要はありません。

Oracle Client 11.1.0.7ライブラリを使用するOCIプログラムは、TimesTenで実行するために再コンパイルまたは再リンクする必要はありません。

OCIからTimesTenデータ・ストアへの接続

TimesTen OCIでは、Oracle Instant Clientを使用してTimesTenデータベースに接続します。 Oracle Databaseに接続する場合と同様に、tnsnamesまたはeasy connectのいずれかのネーミング・メソッドを使用してデータベースに接続できます。

この項の内容は次のとおりです。

• tnsnamesネーミング・メソッドを使用した接続

• 簡易接続文字列を使用した接続

• 使用する接続方法の設定（tnsnames.oraまたは簡易接続）

tnsnames、簡易接続およびtnsnames.oraファイルの詳細は、『Oracle Database Net Services管理者ガイド』のネーミング・メソッドの構成に関する項を参照してください。

注意: sqlnetメカニズムはTimesTen OCI接続に使用されますが、接続はOracle sqlnetドライバではなく、TimesTen ODBCドライバを介して行われます。 TimesTenデータ・ストアに接続するための権限は、CREATE SESSION権限を使用して、インスタンス管理者以外のすべてのユーザーに明示的に付与する必要があります。「接続のアクセス制御」を参照してください。 オペレーティング・システムのユーザー名がインスタンス管理者のユーザー名と同じ場合は、一重引用符と大カッコ内にユーザー名を指定し、パスワードに空の文字列を使用して（たとえば、ユーザーに"[myname]"、パスワードに""）、OCIでインスタンス管理者として接続できます。

tnsnamesネーミング・メソッドを使用した接続

TimesTenでは、tnsnames構文がサポートされています。 TimesTen tnsnames.oraエントリは、Oracle tnsnames.oraエントリの場合と同様に使用できます。

次に、tnsnames.oraでのTimesTenエントリの構文を示します。

tns_entry = (DESCRIPTION =
              (CONNECT_DATA =
                (SERVICE_NAME = dsn)
                (SERVER = timesten_direct | timesten_client)))

ここで、tns_entryは、エントリに割り当てる任意のTNS名です。 これは、OCILogon()、OCILogon2()およびOCIServerAttach()コールでdbname引数として使用できます。

ここで示されているように、DESCRIPTIONおよびCONNECT_DATAは必要です。

SERVICE_NAMEでは、dsnは、OCIアプリケーションを実行しているユーザーが表示できるodbc.iniファイルまたはsys.odbc.iniファイルで構成されたTimesTen DSNである必要があります。 Windowsでは、DSNはODBC Data Source Administratorを使用して指定できます。 『Oracle TimesTen In-Memory Databaseオペレーション・ガイド』のTimesTenデータ・ストアの作成に関する項を参照してください。

SERVERの場合は、timesten_directでTimesTenへの直接接続を指定するか、timesten_clientでクライアント/サーバー接続を指定します。 timesten_clientを選択した場合、DSNをクライアント/サーバー・データ・ストアとして構成する必要があります。

通常どおり、TimesTenサーバーのホストおよびポートは、sys.ttconnect.iniファイルのエントリからDSNに基づいて決定されます。 『Oracle TimesTen In-Memory Databaseオペレーション・ガイド』のTimesTen ClientおよびTimesTen Serverの使用に関する項を参照してください。

次に、直接接続のtnsnames.oraエントリの例を示します。

my_tnsname = (DESCRIPTION =
               (CONNECT_DATA =
                 (SERVICE_NAME = my_dsn)
                 (SERVER = timesten_direct)))

TNS名my_tnsnameは、次のいずれかの方法で使用できます。

• OCIログオン・コールでmy_tnsnameをdbname引数に指定します。

• dbnameに空の文字列を指定し、TWO_TASKまたはLOCALをmy_tnsnameに設定します。

次に例を示します。

OCILogon2(envhp, errhp, &svchp,
         (text *)"user1", (ub4)strlen("user1"),
         (text *)"pwd1", (ub4)strlen("pwd1"),
         (text *)"my_tnsname", (ub4)strlen((char*)"my_tnsname"), OCI_DEFAULT));

OCIログオンのコール・シーケンスの詳細は、『Oracle Call Interface Programmer's Guide』の接続関数、認証関数および初期化関数に関する項を参照してください。

またはUNIXシステムでは、たとえば、my_tnsnameにTWO_TASKを設定し、dbnameに空の文字列を指定してOCIログオン・コールを使用します。

OCILogon2(envhp, errhp, &svchp,
         (text *)"user1", (ub4)strlen("user1"),
         (text *)"pwd1", (ub4)strlen("pwd1"),
         (text *)"", (ub4)0, OCI_DEFAULT));

簡易接続文字列を使用した接続

TimesTenでは簡易接続構文がサポートされています。簡易接続構文では、tnsnames.oraを構成しなくても接続できるため、Instant Clientパッケージがさらに便利になります。 簡易接続文字列は、URLに似た次の形式の構文を持ちます。

[//]host[:port]/service_name:server[/instance]

先頭のダブルスラッシュは任意です。 ホスト名は、簡易接続構文を満たすように指定する必要があります。そうでない場合、TimesTenでは無視されます。 慣例では、名前localhostがよく使用されています。 ポートに指定した値も無視されます。 クライアント/サーバー・モードでは、TimesTenサーバーのホストおよびポートは、sys.ttconnect.iniファイルのエントリからTimesTen DSNに基づいて決定されます。

service_nameにDSNを指定します。 必要に応じて、serverにtimesten_clientまたはtimesten_directを指定します。

TimesTenでは、instanceフィールドは無視されます。指定する必要はありません。

たとえば、次の簡易接続文字列では、クライアント/サーバー・ライブラリを使用してTimesTenサーバーに接続します。 odbc.iniファイルのDSN ttclientがクライアント/サーバー・データソースとして解決され、sys.ttconnect.iniファイルで指定された対応するホストおよびポートに接続することを想定しています。

"localhost/ttclient:timesten_client"

次の簡易接続文字列は、TimesTenへの直接接続の場合のものです。 DSN ttdirectがodbc.iniで定義されることを想定しています。

"localhost/ttdirect:timesten_direct"

簡易接続文字列は次のいずれかの方法で使用できます。

• OCIログオン・コールでdbname引数に指定します。

• dbnameに空の文字列を指定し、TWO_TASKまたはLOCALに簡易接続文字列を一重引用符で囲んで設定します。

次に例を示します。

OCILogon2(envhp, errhp, &svchp,
         (text *)"user1", (ub4)strlen("user1"),
         (text *)"pwd1", (ub4)strlen("pwd1"),
         (text *)"localhost/ttclient:timesten_client",
         (ub4)strlen((char*)"localhost/ttclient:timesten_client"), OCI_DEFAULT));

OCIログオンのコール・シーケンスの詳細は、『Oracle Call Interface Programmer's Guide』の接続関数、認証関数および初期化関数に関する項を参照してください。

またはUNIXシステムでは、たとえば、localhost/ttclient:timesten_clientにTWO_TASKを設定し、dbnameに空の文字列を指定してOCIログオン・コールを使用します。

OCILogon2(envhp, errhp, &svchp,
         (text *)"user1", (ub4)strlen("user1"),
         (text *)"pwd1", (ub4)strlen("pwd1"),
         (text *)"", (ub4)0, OCI_DEFAULT));

使用する接続方法の設定（tnsnames.oraまたは簡易接続）

sqlnet.oraファイルが存在する場合、このファイルは、試行するネーミング・メソッドおよびその試行順序を指定します。 sqlnet.oraが存在しても、特定のネーミング・メソッドが含まれていない場合、そのメソッドは使用できません。 sqlnet.oraが存在しない場合は、いずれのメソッドも使用できます。 Instant Clientは、TNS_ADMINの場所でsqlnet.oraファイルを検索します（該当する場合）。 デフォルトの場所は、ORACLE_HOME/network/adminです。

次に、TimesTenに用意されているsqlnet.oraファイルを示します。このファイルでは、tnsnamesと簡易接続（EZCONNECT）の両方がサポートされます。

# To use ezconnect syntax or tnsnames, the following entries must be
# included in the sqlnet.ora configuration.
#
NAMES.DIRECTORY_PATH= (TNSNAMES, EZCONNECT)

TimesTenでは、このファイルによって、最初にOCIログオン・コール内のtnsnames構文が検索されます。 tnsnames構文を検出できなかった場合、簡易接続構文が検索されます。

注意: TimesTenでは、tnsnames.oraおよびsqlnet.oraのサンプル・コピーはinstall_dir/network/admin/samplesディレクトリにあります。

エラー・レポート

TimesTen OCIアプリケーションのエラーでは、Oracleエラー・コードが返されます。TimesTenでは、同様の状況でOracleがレポートするOracleエラー・コードと同じOracleエラー・コードをレポートしようとします。エラー・メッセージは、TimesTenカタログまたはOracleカタログのいずれかから取得されます。エラー・メッセージによっては、TimesTenエラー・コードが付随している場合もあります（該当する場合）。

致命的なエラーとは、エラー・リカバリが終わるまでデータ・ストアにアクセスできなくなるエラーのことです。致命的なエラーが発生すると、すべてのデータ・ストアの接続を切断する必要があります。それ以後の処理は完了されません。 OCIの致命的なエラーは、Oracleエラー・コードORA-03135またはORA-00600で示されます。これらのエラーの処理は、標準的なエラーの処理とは異なります。具体的には、アプリケーションのエラー処理コードにデータ・ストアとの接続を切断するコードを含める必要があります。

OCIのデモ・プログラム

TimesTenにはOCIデモ・プログラムが付属しています。 これらのプログラムはquickstart/sample_code/ociディレクトリにあります。このディレクトリのREADMEファイルに、デモのコンパイル方法および実行方法が記載されています。

詳細は、クイック・スタートのようこそページ（install_dir/quickstart.html）を参照してください。

TimesTen OCIのその他の機能

この項では、TimesTen OCIを使用する開発者向けに次の内容について説明します。

• TimesTenの遅延準備

• OCIでのIMDB Cacheの使用

• TimesTen OCIでの重複したパラメータのバインド

TimesTenの遅延準備

OCIでは、準備コールはクライアントで実行される軽量処理であることが期待されています。 TimesTenがこの期待される動作との一貫性を実現し、クライアントとサーバー間の不要なラウンドトリップを回避するため、TimesTenクライアント・ライブラリに実装されたSQLPrepareでは、遅延準備と呼ばれる処理が実行されます。この処理では、リクエストは要求されるまでサーバーに送信されません。 詳細は、「TimesTenの遅延準備」を参照してください。

OCIでのIMDB Cacheの使用

この項では、IMDB Cacheの使用に関するTimesTen OCI機能について説明します。

• OCIでのIMDB Cache用Oracleパスワードの指定

• アクションの影響を受けるキャッシュ・グループの数の確認

OCIでのIMDB Cache用Oracleパスワードの指定

IMDB Cacheを使用するには、キャッシュされたOracle表からの選択およびその更新が可能なOracle Databaseユーザーと同じ名前を持つキャッシュ・ユーザーがTimesTenデータベースに存在している必要があります。たとえば、このOracleユーザーは、キャッシュ管理ユーザーまたはスキーマ・ユーザーであることができます。TimesTenキャッシュ・ユーザーのパスワードは、同じ名前を持つOracleユーザーと別のパスワードにすることができます。詳細は、『Oracle In-Memory Database Cacheユーザーズ・ガイド』のキャッシュ・インフラストラクチャの設定に関する項を参照してください。

OCIをIMDB Cacheで使用する場合、TimesTenでは、OCIを介してOracleユーザーのパスワードを渡すことができます。それには、TimesTenへのログイン時にOCILogon()またはOCILogon2()コールのパスワード・フィールドにOracleユーザーのパスワードを追加します。次の例のように、接続文字列で属性OraclePWDを使用します。

text *cacheuser = (text *)"cacheuser1";
text *cachepwds = (text *)"ttpwd;OraclePWD=orclpwd";
text *ttdbname = (text *)"tt_tnsname";
....
OCILogon2(envhp, errhp, &svchp,
       (text *)cacheuser, (ub4)strlen(cacheuser),
       (text *)cachepwds, (ub4)strlen(cachepwds),
       (text *)ttdbname, (ub4)strlen(ttdbname), OCI_DEFAULT));

OracleユーザーのパスワードがTimesTenユーザーのパスワードと同じ場合でも、常にOraclePWDを指定する必要があります。

この例での指定内容は次のとおりです。

• cacheuser1は、キャッシュされたOracle表にアクセスできるOracleユーザーの名前であると同時に、TimesTenキャッシュ・ユーザーの名前です。

• ttpwdは、TimesTenキャッシュ・ユーザーのパスワードです。

• orclpwdは、Oracleユーザーのパスワードです。

• tt_tnsnameは、接続するTimesTenデータベースのTNS名です。

Oracleデータベースは、odbc.iniファイルまたはsys.odbc.iniファイルのTimesTen OracleNetServiceName接続属性を使用して指定します。

あるいは、TNS名を使用するかわりに、簡易接続構文またはTWO_TASK環境変数かLOCAL環境変数を使用することもできます（前の項を参照）。

アクションの影響を受けるキャッシュ・グループの数の確認

TimesTen OCIでは、FLUSH CACHE GROUP、LOAD CACHE GROUP、REFRESH CACHE GROUPまたはUNLOAD CACHE GROUP文の実行の後、OCI_ATTR_ROW_COUNT引数を指定したOCI関数OCIAttrGet()を使用すると、フラッシュ、ロード、リフレッシュまたはアンロードされたキャッシュ・インスタンスの数が返されます。

詳細は、『Oracle In-Memory Database Cacheユーザーズ・ガイド』の処理の影響を受けるキャッシュ・インスタンスの数の確認に関する項を参照してください。

TimesTen OCIでの重複したパラメータのバインド

SQL文で重複したパラメータをバインドするための、2つのサポートされているモード（Oracleモードまたは従来のTimesTenモード）については、「SQL文での重複したパラメータのバインド」を参照してください。 TimesTen OCIでは、Oracleモードのみがサポートされています。

第1章と同様に、次の問合せについて検討します。

SELECT * FROM employees
  WHERE employee_id < :a AND manager_id > :a AND salary < :b;

OCIでは、通常、Oracleモードの場合と同様に、パラメータaが2回出現すると別のパラメータとみなされます。 ただし、OCIでは、aを両方ともOCIBindByPos()への1つのコールとバインドすることができます。

OCIBindByPos(..., 1, ...); /* both occurrences of :a */
OCIBindByPos(..., 3, ...); /* occurrence of :b */

また、OCIでは2つのaを別々にバインドすることもできます。

OCIBindByPos(..., 1, ...); /* first occurrence of :a */
OCIBindByPos(..., 2, ...); /* second occurrence of :a */
OCIBindByPos(..., 3, ...); /* occurrence of :b */

両方の場合で、パラメータbは位置3に存在するとみなされていることに注意してください。

注意: また、OCIでは、OCIBindByName()を使用して位置ではなく、名前でバインドすることもできます。

コール、ハンドル、記述子、SQLデータ型およびパラメータ属性のサポート

表3-2に、OCIコールのTimesTenサポートを示します。この内容は、Oracle Databaseリリース11.1.0.7に関して記述されています。

TimesTenでサポートされていない機能に関連するコールのグループは、名前にアスタリスクを付けて示されている場合があります。 たとえば、TimesTenでは、アドバンスト・キューイングはサポートされていません。 アドバンスト・キューイングに関連するコールは、OCIAQで始まる名前を持ち、表ではOCIAQ*()と示されています。

TimesTenでサポートされているコールのグループの中には、表でアスタリスクを付けて示されているものもあります。 たとえば、TimesTen OCIでは、OCIDate*()と示されているOCI日付関数がサポートされます。

表3-2 TimesTen OCIコールのサポート

OCIコール	サポート	注意
OCIAQ*()	なし	TimesTenでは、アドバンスト・キューイングはサポートされていません。
OCIAnyData*()	なし	TimesTenではANYDATAはサポートされていません。
OCIAppCtxClearAll()	あり
OCIAppCtxSet()	あり
OCIArrayDescriptorAlloc()	あり
OCIArrayDescriptorFree()	あり
OCIAttrGet()	あり	TimesTenサポートには、キャッシュ・グループでの特別な使用方法が含まれています。 「OCIでのIMDB Cacheの使用」を参照してください。
OCIAttrSet()	あり
OCIBinXml*()	なし	TimesTenでは、XML DBはサポートされていません。
OCIBindArrayOfStruct()	あり	SQL文ではサポートされていますが、PL/SQLではサポートされていません。
OCIBindByName()	あり	modeパラメータでは次の値はサポートされていません。 OCI_DATA_AT_EXEC OCI_IOV
OCIBindByPos()	あり	modeパラメータでは次の値はサポートされていません。 OCI_DATA_AT_EXEC OCI_IOV
OCIBindDynamic()	なし
OCIBindObject()	なし	TimesTenでは、ユーザー定義オブジェクトはサポートされていません。
OCIBreak()	なし
OCICache*()	なし	TimesTenでは、ユーザー定義オブジェクトはサポートされていません。
OCICharSetConversionIsReplacementUsed()	あり
OCICharSetToUnicode()	あり
OCIClientVersion()	あり
OCIColl*()	なし	TimesTenでは、コレクションはサポートされていません。
OCIConnectionPoolCreate()	なし
OCIConnectionPoolDestroy()	なし
OCIContext*()	なし	TimesTenでは、データ・カートリッジはサポートされていません。
OCIDBShutdown()	なし
OCIDBStartup()	なし
OCIDate*()	あり	記述子のサポートの詳細は、表3-4を参照してください。
OCIDefineArrayOfStruct()	あり	SQL文ではサポートされていますが、PL/SQLではサポートされていません。
OCIDefineByPos()	あり
OCIDefineDynamic()	なし
OCIDefineObject()	なし
OCIDescribeAny()	あり	objptr_typパラメータでは次の値はサポートされていません。 OCI_OTYPE_REF OCI_OTYPE_PTR objtypパラメータでは次の値はサポートされていません。 OCI_PTYPE_PKG OCI_PTYPE_SYN OCI_PTYPE_TYPE
OCIDescriptorAlloc()	あり
OCIDescriptorFree()	あり
OCIDirPath*()	なし	TimesTenではダイレクト・パス・ロードはサポートされていません。
OCIDuration*()	なし	TimesTenでは、データ・カートリッジはサポートされていません。
OCIEnvCreate()	あり	modeパラメータでは次の値はサポートされていません。 OCI_EVENTS OCI_NEW_LENGTH_SEMANTICS OCI_NCHAR_LITERAL_REPLACE_ON OCI_NCHAR_LITERAL_REPLACE_OFF OCI_NO_MUTEX（かわりにOCI_ENV_NO_MUTEXを使用します）
OCIEnvInit()	あり	modeパラメータでは次の値はサポートされていません。 OCI_NO_MUTEX OCI_ENV_NO_MUTEX 注意: OCIEnvInitのかわりにOCIEnvCreate()を使用します。 OCIEnvInit()は下位互換性を保つためにサポートされています。
OCIEnvNlsCreate()	あり	modeパラメータでは次の値はサポートされていません。 OCI_EVENTS OCI_NCHAR_LITERAL_REPLACE_ON OCI_NCHAR_LITERAL_REPLACE_OFF OCI_NO_MUTEX（かわりにOCI_ENV_NO_MUTEXを使用します）
OCIErrorGet()	あり
OCIExtProc*()	なし	TimesTenでは、データ・カートリッジはサポートされていません。
OCIExtract*()	なし	TimesTenでは、データ・カートリッジはサポートされていません。
OCIFile*()	なし	TimesTenでは、データ・カートリッジはサポートされていません。
OCIFormatInit()	なし	TimesTenでは、データ・カートリッジはサポートされていません。
OCIFormatString()	なし	TimesTenでは、データ・カートリッジはサポートされていません。
OCIFormatTerm()	なし	TimesTenでは、データ・カートリッジはサポートされていません。
OCIHandleAlloc()	あり
OCIHandleFree()	あり
OCIInitialize()	あり	modeパラメータでは次の値はサポートされていません。 OCI_NO_MUTEX OCI_ENV_NO_MUTEX 注意: OCIInitialize()のかわりにOCIEnvCreate()を使用します。 OCIInitialize()は下位互換性を保つためにサポートされています。
OCIInterval*()	あり	記述子のサポートの詳細は、表3-4を参照してください。
OCIIter*()	なし	TimesTenでは、コレクションはサポートされていません。
OCILdaToSvcCtx()	なし
OCILob*()	なし	TimesTenでは、LOBデータ型はサポートされていません。
OCILogoff()	あり
OCILogon()	あり
OCILogon2()	あり	modeパラメータでは、OCI_DEFAULT値のみがサポートされています。
OCIMemory*()	なし	TimesTenでは、データ・カートリッジはサポートされていません。
OCIMessage*()	なし	TimesTenでは、データ・カートリッジはサポートされていません。
OCIMultiByte*()	あり
OCINls*()	あり
OCINumber*()	あり
OCIObject*()	なし	TimesTenでは、ユーザー定義オブジェクトはサポートされていません。
OCIParamGet()	あり
OCIParamSet()	あり
OCIPasswordChange()	なし
OCIPing()	あり
OCIRaw*()	あり
OCIRef*()	なし
OCIReset()	なし
OCIRowidToChar()	あり
OCIServer*()	あり	OCIServerAttachのmodeパラメータでは、OCI_DEFAULT値のみがサポートされています。
OCISessionBegin()	あり	credtパラメータでは、OCI_CRED_RDBMS値のみがサポートされています。 modeパラメータでは、OCI_DEFAULT値のみがサポートされています。
OCISessionEnd()	あり
OCISessionGet()	あり
OCISessionPoolCreate()	なし
OCISessionPoolDestroy()	なし
OCISessionRelease()	あり
OCISharedLibInit()	なし
OCIStmtExecute()	あり	modeパラメータでは次の値はサポートされていません。 OCI_BATCH_ERRORS OCI_EXACT_FETCH OCI_STMT_SCROLLABLE_READONLY 注意: OCI_COMMIT_ON_SUCCESSを使用すると、トランザクションをコミットするためのサーバーへの余分なラウンドトリップが回避され、パフォーマンスが向上します。
OCIStmtFetch()	あり
OCIStmtFetch2()	あり	orientationパラメータでサポートされる値は、OCI_DEFAULTおよびOCI_FETCH_NEXTのみです。
OCIStmtGetBindInfo()	あり
OCIStmtGetPieceInfo()	なし
OCIStmtPrepare()	あり	languageパラメータでサポートされる値は、OCI_NTV_SYNTAXのみです。 注意: TimesTenでは、OCIStmtPrepare()で文のキャッシュはサポートされていません。 次のOCIStmtPrepare2()を参照してください。
OCIStmtPrepare2()	あり	modeパラメータでサポートされる値は、OCI_DEFAULTのみです。 文のキャッシュについては、TimesTenでは、OCIStmtPrepare2()またはOCIStmtRelease()への将来のコール用に、文にタグを付けるためのkey引数がサポートされています。
OCIStmtRelease()	あり	modeパラメータでサポートされる値は、OCI_DEFAULTのみです。 文のキャッシングについては、TimesTenでは、文にタグを付けるためのkey引数がサポートされています。 これには、OCIStmtPrepare2()から返されたキーを指定できます。
OCIStmtSetPieceInfo()	なし
OCIString*()	あり
OCISubscription*()	なし	TimesTenでは、アドバンスト・キューイングはサポートされていません。
OCISvcCtxToLda()	なし
OCITable*()	なし
OCITerminate()	なし
OCIThread*()	あり
OCITransCommit()	あり	modeパラメータでサポートされる値は、OCI_DEFAULTのみです。
OCITransDetach()	なし
OCITransForget()	なし
OCITransMultiPrepare()	なし
OCITransPrepare()	なし
OCITransRollback()	あり
OCITransStart()	なし
OCIType*()	なし
OCIUnicodeToCharSet()	あり
OCIUserCallbackGet()	あり
OCIUserCallbackRegister()	あり
OCIWideChar*()	あり
OCIXmlDbFreeXmlCtx()	なし	TimesTenでは、XML DBはサポートされていません。
OCIXmlDbInitXmlCtx()	なし	TimesTenでは、XML DBはサポートされていません。

表3-3に、TimesTen OCIでサポートされているハンドルおよび属性を示します。

表3-3 TimesTen OCIでサポートされているハンドルおよび属性

ハンドル	Cオブジェクト	サポートされる属性
環境	OCIEnv	OCI_ATTR_ENV_CHARSET_ID OCI_ATTR_ENV_NCHARSET_ID OCI_ATTR_ENV_UTF16 OCI_ATTR_EVTCTX OCI_ATTR_OBJECT
エラー	OCIError	OCI_ATTR_DML_ROW_OFFSET
サービス・コンテキスト	OCISvcCtx	OCI_ATTR_ENV OCI_ATTR_IN_V8_MODE OCI_ATTR_SERVER OCI_ATTR_SESSION OCI_ATTR_TRANS
文	OCIStmt	OCI_ATTR_BIND_COUNT OCI_ATTR_CURRENT_POSITION OCI_ATTR_ENV OCI_ATTR_FETCH_ROWID OCI_ATTR_NUM_DML_ERRORS OCI_ATTR_PARAM_COUNT OCI_ATTR_PREFETCH_MEMORY OCI_ATTR_PREFETCH_ROWS OCI_ATTR_ROW_COUNT OCI_ATTR_ROWID OCI_ATTR_ROWS_FETCHED OCI_ATTR_SQLFNCODE OCI_ATTR_STATEMENT OCI_ATTR_STMT_TYPE
バインド	OCIBind	OCI_ATTR_CHARSET_FORM OCI_ATTR_CHARSET_ID OCI_ATTR_MAXCHAR_SIZE OCI_ATTR_MAXDATA_SIZE
定義	OCIDefine	OCI_ATTR_CHARSET_FORM OCI_ATTR_CHARSET_ID OCI_ATTR_MAXCHAR_SIZE
記述	OCIDescribe	OCI_ATTR_PARAM OCI_ATTR_PARAM_COUNT
サーバー	OCIServer	OCI_ATTR_ENV OCI_ATTR_IN_V8_MODE OCI_ATTR_SERVER_GROUP OCI_SERVER_STATUS
ユーザー・セッション	OCISession	OCI_ATTR_CLIENT_IDENTIFER OCI_ATTR_CLIENT_INFO OCI_ATTR_CURRENT_SCHEMA OCI_ATTR_DRIVER_NAME OCI_ATTR_INITIAL_CLIENT_ROLES OCI_ATTR_MODULE OCI_ATTR_PROXY_CREDENTIALS OCI_ATTR_USERNAME
認証	OCIAuthInfo	ユーザー・セッション・ハンドルの場合と同じです。
トランザクション	OCITrans	OCI_ATTR_TRANS_NAME OCI_ATTR_TRANS_TIMEOUT
スレッド	OCIThreadHandle

表3-4に、TimesTen OCIでサポートされている記述子を示します。

表3-4 TimesTen OCIでサポートされている記述子

記述子	Cオブジェクト
パラメータ（読取り専用）	OCIParam
ROWID	OCIRowid
ANSI DATE	OCIDateTime
TIMESTAMP	OCIDateTime
TIMESTAMP WITH TIME ZONE	OCIDateTime
TIMESTAMP WITH LOCAL TIME ZONE	OCIDateTime
INTERVAL YEAR TO MONTH	OCIInterval
INTERVAL DAY TO SECOND	OCIInterval
ユーザー・コールバック	OCIUcb

表3-5に、TimesTen OCIでサポートされているSQLデータ型を示します。

表3-5 TimesTen OCIでサポートされているSQLデータ型

SQLデータ型	注意
SQLT_AFC
SQLT_AVC
SQLT_BDOUBLE
SQLT_BFLOAT
SQLT_BIN
SQLT_CHR
SQLT_DAT
SQLT_DATE
SQLT_FLT
SQLT_IBDOUBLE
SQLT_IBFLOAT
SQLT_INT
SQLT_INTERVAL_DS	TimesTenには格納されていません。
SQLT_INTERVAL_YM	TimesTenには格納されていません。
SQLT_LBI
SQLT_LNG
SQLT_LVB	TimesTenに格納されるときに4MBで切り捨てられます。
SQLT_LVC	TimesTenに格納されるときに4MBで切り捨てられます。
SQLT_NUM
SQLT_ODT
SQLT_RDD	ROWIDはOracle形式で返されます。
SQLT_RSET	1文につき1つの結果セット・パラメータのみが許可されます。
SQLT_STR
SQLT_TIME
SQLT_TIME_TZ	TimesTenに格納されるときにタイムゾーンは無視されます。
SQLT_TIMESTAMP
SQLT_TIMESTAMP_LTZ	TimesTenに格納されるときにタイムゾーンは無視されます。
SQLT_TIMESTAMP_TZ	TimesTenに格納されるときにタイムゾーンは無視されます。
SQLT_UIN
SQLT_VBI
SQLT_VCS
SQLT_VNU
SQLT_VST

表3-6に、サポートされているパラメータ属性を示します。

表3-6 TimesTen OCIでサポートされているパラメータ属性

パラメータ	サポートされる属性
すべてのパラメータ	OCI_ATTR_NUM_PARAMS OCI_ATTR_OBJ_NAME OCI_ATTR_OBJ_SCHEMA OCI_ATTR_PTYPE
表およびビュー・パラメータ	OCI_ATTR_NUM_COLS OCI_ATTR_LIST_COLUMNS
PL/SQLプロシージャおよび関数パラメータ	OCI_ATTR_LIST_ARGUMENTS
PL/SQLサブプログラム・パラメータ	OCI_ATTR_LIST_ARGUMENTS OCI_ATTR_NAME
PL/SQLパッケージ・パラメータ	OCI_ATTR_LIST_SUBPROGRAMS
順序パラメータ	OCI_ATTR_OBJID OCI_ATTR_MIN OCI_ATTR_MAX OCI_ATTR_INCR OCI_ATTR_CACHE OCI_ATTR_ORDER OCI_ATTR_HW_MARK
列パラメータ	OCI_ATTR_CHAR_USED OCI_ATTR_CHAR_SIZE OCI_ATTR_DATA_SIZE OCI_ATTR_DATA_TYPE OCI_ATTR_NAME OCI_ATTR_PRECISION OCI_ATTR_SCALE OCI_ATTR_IS_NULL OCI_ATTR_TYPE_NAME OCI_ATTR_SCHEMA_NAME OCI_ATTR_CHARSET_ID OCI_ATTR_CHARSET_FORM
引数および結果パラメータ	OCI_ATTR_NAME OCI_ATTR_POSITION OCI_ATTR_DATA_TYPE OCI_ATTR_DATA_SIZE OCI_ATTR_PRECISION OCI_ATTR_SCALE OCI_ATTR_LEVEL OCI_ATTR_IS_NULL OCI_ATTR_CHARSET_ID OCI_ATTR_CHARSET_FORM
リスト・パラメータ	OCI_LTYPE_COLUMN OCI_LTYPE_SCH_OBJ OCI_LTYPE_DB_SCH
データベース・パラメータ	OCI_ATTR_VERSION OCI_ATTR_CHARSET_ID OCI_ATTR_NCHARSET_ID OCI_ATTR_LIST_SCHEMAS OCI_ATTR_MAX_PROC_LEN OCI_ATTR_MAX_COLUMN_LEN OCI_ATTR_ATTR_CURSOR_COMMIT_BEHAVIOR OCI_ATTR_MAX_CATALOG_NAMELEN OCI_ATTR_CATALOG_LOCATION OCI_ATTR_SAVEPOINT_SUPPORT OCI_ATTR_NOWAIT_SUPPORT OCI_ATTR_AUTOCOMMIT_DDL OCI_ATTR_LOCKING_MODE