TimesTenの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用の環境変数
変数 | 必須またはオプション | 設定 |
---|---|---|
|
必須 |
パス内で、TimesTen Instant ClientディレクトリがOracle Databaseライブラリより前になるように設定する必要があります。このパスは、 bin/ttenv |
|
|
「OCIからTimesTenデータベースへの接続」を参照してください。 |
|
オプション |
OCIログオン・コールで 「OCIからTimesTenデータベースへの接続」を参照してください。 |
|
オプション |
「文字セットの指定」を参照してください。文字セット・コンポーネントのみが適用され、TimesTenでサポートされている文字セットを示している必要があります。言語および地域の値は無視されます。 この環境変数は、TimesTenのデフォルトの文字セットよりも優先されます。 |
|
オプション |
「その他のグローバリゼーション機能」を参照してください。ソート順序は、TimesTenでサポートされている値である必要があります。 この環境変数は、TimesTenの |
|
オプション |
「その他のグローバリゼーション機能」を参照してください。 この環境変数は、TimesTenの |
|
オプション |
「その他のグローバリゼーション機能」を参照してください。 この環境変数は、TimesTenの |
ノート:
『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にのみ適用されます。
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エラー・レポート
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作成の制御および障害診断の無効化を参照してください。