TimesTenのOCIの概要

TimesTen OCIアプリケーションの使用を始めるには、次の方法を使用します。

• TimesTenのOCI用の環境変数

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

• OCIからTimesTenデータベースへの接続

• OCIエラー処理

• シグナル処理および診断フレームワークの考慮事項

TimesTenのOCI用の環境変数

TimesTen OCIアプリケーションを実行するための特定の環境変数を設定します。

設定は、特に記述のないかぎり、直接接続とクライアント/サーバー接続の両方に適用されます。

表3-1を参照してください。

ノート:

• インスタンスの作成後、必要に応じて、ご使用のオペレーティング・システムに適用可能なtimesten_home/bin/ttenvスクリプトを介して環境を設定できます。ttenvスクリプトについては、『Oracle TimesTen In-Memory Databaseインストレーション、移行およびアップグレード・ガイド』の環境変数を参照してください。

• TimesTenで動作するOCIプログラムが適切に生成されるようにするために、OCIコンパイルにはORACLE_HOMEを設定できません。

表3-1 TimesTenのOCI用の環境変数

変数	必須またはオプション	設定
LD_LIBRARY_PATH (LinuxまたはUNIX) PATH (Windows)	必須	パス内で、TimesTen Instant ClientディレクトリがOracle Databaseライブラリより前になるように設定する必要があります。このパスは、timesten_homeの下にある次のスクリプトを使用すると適切に設定されます。 bin/ttenv
TNS_ADMIN	tnsnamesネーミング・メソッドを使用する場合は必須	tnsnames.oraファイルを保存するディレクトリを指定します。これは、TimesTenがsqlnet.oraファイルを検索するディレクトリでもあります。 「OCIからTimesTenデータベースへの接続」を参照してください。
TWO_TASK (Linuxまたは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一般接続属性よりも優先されます。

ノート:

『Oracle TimesTen In-Memory Databaseリファレンス』のNLSの一般接続属性を参照してください。

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

OCIアプリケーションをコンパイルおよびリンクするステップについて、Oracle DatabaseとTimesTenの間に変更は必要ありません。

TimesTenとともに出荷されたOracle Clientライブラリを使用するOCIプログラムは、TimesTenとともに提供されるOracleバージョンへのメジャー・アップグレードがある場合を除き、TimesTenで実行するために再コンパイルまたは再リンクする必要はありません。

OCIからTimesTenデータベースへの接続

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

この項では、次のトピックを取り扱います次のうち最初を除くすべては、TimesTen Classicにのみ適用されます。

• TimesTen ScaleoutでのOCI接続の構成について

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

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

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

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

ノート:

sqlnetメカニズムはTimesTen OCI接続に使用されますが、接続はOracle Databasesqlnetドライバではなく、TimesTen ODBCドライバを介して行われます。

TimesTen ScaleoutでのOCI接続の構成について

TimesTen Scaleoutでは、すべてのインスタンスで、必要に応じて、tnsnames.oraファイルおよびsqlnet.oraファイルに、これまで定義したすべてのTimesTen接続可能オブジェクトのエントリが自動的に移入されます。

『Oracle TimesTen In-Memory Databaseリファレンス』の接続可能オブジェクトの操作を参照してください。

ユーザーがこれらのエントリを手動で構成することは許可されていないため、ここに示されている手順は関係ありません。tnsnames、sqlnet、およびOracleデータベース接続のエントリ(該当する場合)など追加のエントリに関連する情報を取得して配布するには、ttGridAdmin TNSNamesImportコマンドおよびSQLNetImportコマンドを使用します。『Oracle TimesTen In-Memory Databaseリファレンス』のOracle Databaseの操作を参照してください。

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

TimesTenでは、tnsnames構文がサポートされています。TimesTenのtnsnames.oraエントリは、Oracle Databaseの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アプリケーションを実行しているユーザーが表示可能なsys.odbc.iniまたはユーザー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クライアントおよびサーバーの使用を参照してください。

次に、直接接続の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プログラマーズ・ガイド』の接続関数、認証関数および初期化関数を参照してください。

または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 Classicの場合、(TNS_ADMIN環境変数に加えて) ttInstanceCreate -tnsadminオプションまたはttInstanceModify -tns_adminオプションを使用して、tnsnamesの場所を設定できます。『Oracle TimesTen In-Memory Databaseリファレンス』のttInstanceCreateおよびttInstanceModifyを参照してください。

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

TimesTenでは簡易接続構文がサポートされており、tnsnames.oraを構成しなくても接続できるため、Instant Clientパッケージがさらに便利になります。

簡易接続文字列は、URLに似た次の形式の構文を使用します。

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

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

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

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

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

"localhost/ttclient:timesten_client"

次の簡易接続文字列は、TimesTenへの直接接続の場合のものです。DSN ttdirectがsys.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プログラマーズ・ガイド』の接続関数、認証関数および初期化関数を参照してください。

または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ファイルが存在する場合、このファイルは、試行するネーミング・メソッドおよびその試行順序を指定します。

Instant Clientは、TNS_ADMINの場所でsqlnet.oraファイルを検索します(該当する場合)。TNS_ADMINではなくORACLE_HOMEが設定されている場合(以前のInstant Clientインストールでそうなっていた場合など)、デフォルトのsqlnet.oraの場所は、ORACLE_HOME/network/adminになります(『Oracle Database Net Servicesリファレンス』のsqlnet.oraファイルのパラメータを参照)。

sqlnet.oraが存在していても、特定のネーミング・メソッドを指定していない場合、そのメソッドは使用できません。sqlnet.oraが存在しない場合は、いずれのメソッドも使用できます。

TimesTenでは、timesten_home/install/network/admin/samplesディレクトリにあるtnsnames.oraおよびsqlnet.oraのサンプル・コピーにアクセスできます。次に、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構文を検出できなかった場合、簡易接続構文が検索されます。

OCIエラー処理

OCIエラー処理には、エラー・レポートと一時的エラーが含まれます。

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

• OCIエラー・レポート

• 一時的なエラー(OCI)

OCIエラー・レポート

TimesTen OCIアプリケーションのエラーでは、Oracle Databaseのエラー・コードが返されます。

TimesTenでは、同様の状況でOracleがレポートするOracle Databaseエラー・コードと同じエラー・コードをレポートしようとします。エラー・メッセージは、TimesTenエラー・カタログまたはOracle Databaseエラー・カタログのいずれかから取得されます。エラー・メッセージによっては、TimesTenエラー・コードを伴う場合もあります(該当する場合)。

致命的なエラーとは、エラー・リカバリが終わるまでデータベースにアクセスできなくなるエラーのことです。致命的なエラーが発生すると、メモリー不足状態を回避するために、すべてのデータベースの接続を切断する必要があります。それ以後の処理は完了されません。古いTimesTenインスタンスの共有メモリーは、エラー発生時にアクティブだったすべての接続が切断されるまで解放されません。

OCIでの致命的なエラーは、Oracle Databaseエラー・コードORA-03135またはORA-00600で示されます。これらのエラーの処理は、標準的なエラーの処理とは異なります。特に、アプリケーションのエラー処理コードにデータベースとの接続を切断するコードを含める必要があります。

一時的なエラー(OCI)

TimesTenではほとんどの一時的エラーは自動的に解決されますが(これはTimesTen Scaleoutにおいてとりわけ重要です)、アプリケーションで次のエラーが検出された場合は、現在のトランザクションを再試行することをお薦めします。

• ORA-57005:Transient transaction failure due to unavailability of resource.Roll back the transaction and try it again.

ノート:

再試行が適しているかどうかを判断する前に、エラー・スタック全体を検索して、これらのエラー・タイプを返すエラーがないか確認してください。

これは、OCIErrorGet()のerrcodepパラメータで返され、次のいずれかのOCIコールによって発生する可能性があります。

• OCIBindArrayOfStruct()

• OCIBindByName()

• OCIBindByPos()

• OCIDefineArrayOfStruct()

• OCIDefineByPos()

• OCIDescribeAny()

• OCILogoff()

• OCILogon()

• OCILogon2()

• OCIPing()

• OCISessionBegin()

• OCISessionEnd()

• OCISessionGet()

• OCISessionRelease()

• OCIStmtExecute()

• OCIStmtFetch()

• OCIStmtFetch2()

• OCIStmtGetBindInfo()

• OCIStmtPrepare()

• OCIStmtPrepare2()

• OCIStmtRelease()

• OCITransCommit()

• OCITransRollback()

シグナル処理および診断フレームワークの考慮事項

OCIの診断フレームワークでは、アプリケーションで使用しているすべてのシグナル処理に影響する可能性のあるシグナル・ハンドラがインストールされます。OCIのシグナル処理は、sqlnet.oraファイルにDIAG_SIGHANDLER_ENABLED=FALSEを設定することで無効化できます。

『Oracle Call Interfaceプログラマーズ・ガイド』のsqlnet.oraを使用したADR作成の制御および障害診断の無効化を参照してください。