OCIアプリケーションの構築と構成 3

この章では、Linux、UNIXおよびWindowsオペレーティング・システムでのOCIアプリケーションの構築と構成に関する機能について説明します。

他のサポートされているオペレーティング・システムの詳細は、プラットフォーム固有のインストレーション・ガイドを参照してください。

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

• ヘッダー・ファイルおよびMakefileの場所

• LinuxおよびUNIXでのOCIアプリケーションの構築

• Windowsでのアプリケーションの構築

• データベース接続文字列

• 異なるバージョンのタイムゾーン・ファイルで操作するクライアントとサーバー

• oraaccess.xmlを使用するOCIクライアント側デプロイメント・パラメータ

• 互換性およびアップグレードについて

• OCIでの障害診断

3.1 ヘッダー・ファイルおよびMakefileの場所

LinuxおよびUNIXオペレーティング・システムでOCIおよびOCCIクライアント・アプリケーションの開発に必要なOCIおよびOCCIヘッダー・ファイルは、$ORACLE_HOME/rdbms/publicディレクトリにあります。

これらのファイルは、Oracle Databaseサーバー環境でも、Oracle Databaseクライアント管理およびカスタム環境でも使用できます。CおよびC++のヘッダー・ファイルと、Instant Client環境でOCIおよびOCCIアプリケーションを開発するためのMakefileを含むSDKの詳細は、「Oracle Instant Client用のSDK」を参照してください。

すべてのデモ・プログラムとそれらの関連ヘッダー・ファイルは、インストールされると、$ORACLE_HOME/rdbms/demoディレクトリに存在します。これらのデモ・ファイルは、Examplesメディアからのみインストールできます。これらのプログラムの名前とその目的の詳細は、「OCIデモ・プログラム」を参照してください。

demoディレクトリに複数のMakefileが用意されています。各Makefileには、OCI実行可能ファイルを作成する際の指示のコメントが含まれています。コンパイル・エラーとリンク・エラーを回避するために、できるかぎりこれらのデモ用Makefileを使用することをお薦めします。

demo_rdbms.mkファイルは、demoディレクトリにあるサンプルMakefileです。コメントには、デモ用OCIプログラムのビルド方法が含まれています。demo_rdbms.mkファイルには、$ORACLE_HOME/rdbms/publicディレクトリが含まれています。独自のカスタマイズMakefileで、INCLUDEパスに$ORACLE_HOME/rdbms/publicディレクトリがあることを確認してください。

ociucb.mkファイルは、demoにあるコールバック共有ライブラリ作成用Makefileです。

3.2 LinuxおよびUNIXでのOCIアプリケーションの構築

LinuxおよびUNIXでのOCIアプリケーションの構築方法について説明します。

このトピックでは、次の各トピックのLinuxおよびUNIXでのアプリケーション構築に該当するOCIの機能について説明します。

• Oracleディレクトリ構造

• デモ用OCIプログラム

関連項目:

• x86-64 Linuxプラットフォームのオペレーティング・システム要件、x86-64プラットフォームでサポートされるOracle LinuxおよびRedHat Enterpriseディストリビューション、Linux x86-64のプログラミング環境のインストール要件については、『Oracle Database Clientインストレーション・ガイド for Linux』を参照してください。

• ソフトウェア要件を確認するには、『Oracle Database Instant Clientインストレーション・ガイド for Apple Mac OS X (Intel)』を参照してください。

3.2.1 Oracleディレクトリ構造

$ORACLE_HOMEディレクトリには、次の表で説明している、OCIに関連のある次のディレクトリが含まれています。

これらのディレクトリは、Oracle Instant Client用ではなく、完全なクライアントとOracle Database用です。これらのファイルにはOCIアプリケーションのリンクおよび実行に必要なライブラリ・ファイルが含まれ、他のOracle製品とリンクしています。

表3-1 ORACLE_HOMEディレクトリと内容

ディレクトリ名	内容
/admin	構成ファイル
/demo	サンプル・プログラム、Makefile、SQLファイルなど
/imclude	ヘッダー・ファイル
/lib	ライブラリ・ファイル
/mesg	メッセージ・ファイル
/public	パブリック・ヘッダー・ファイル

3.2.2 デモ用OCIプログラム

OCIデモ・プログラムおよびそれらに対応するプロジェクト・ファイルのセットは、必要に応じて、Oracle Databaseのインストール後にインストールされ、ORACLE_BASE/ORACLE_HOME/demoサブディレクトリに設定されます。

OCIアプリケーションの開発ステップを理解するために、これらのOCIデモ・プログラムをビルドし、実行します。

デモ用OCIプログラムをビルドするには、/demoディレクトリにあるmakeファイル(demo_rdbms.mk)を実行します。たとえば、1つのOCIデモをビルドするには、次のmakeコマンド構文を使用します。

make -f demo_rdbms.mk build EXE=demo OBJS="demo.o ..."

たとえば、OCI cdemo81.cプログラムをビルドするには、次のmakeコマンドを入力します。

make -f demo_rdbms.mk build EXE=cdemo81 OBJS=cdemo81.o

この例では、ソース・ファイルcdemo81.cをコンパイルすることで作成されたオブジェクト・ファイルから実行可能ファイルが作成または更新されます。

関連項目:

• Oracle Universal Installerを使用したデモ用OCIプログラムのインストールの詳細は、『Oracle Database Examplesインストレーション・ガイド』を参照してください。

• ORACLE Linux

• demoサブディレクトリで使用可能な他の多くのOCIデモ・プログラム実行についてさらに学習するには、demo_rdbms.mkファイルの内容を確認してください。

• OCIデモ・プログラムの詳細は、「OCIデモ・プログラム」を参照してください。

3.3 Windowsでのアプリケーションの構築

WindowsでのOCIアプリケーションの構築方法について説明します。

詳細は、『OCI for Windowsスタート・ガイド』を参照してください。

関連項目:

Oracle Databaseソフトウェア・クライアント前提要件については、『Oracle Database Clientインストレーション・ガイド for Microsoft Windows』を参照してください。

3.4 データベース接続文字列

このトピックでは、tnsnames.ora、sqlnet.ora、oraaccess.xmlなどの構成ファイルを指定するためにORACLE_BASE_HOMEまたはORACLE_HOMEを使用しないOracle Netネーミング・メソッドについて説明します。

特に、OCIServerAttach()コールのconnect_identifierは、次の形式で指定できます。

• 簡易接続ネーミング文字列の形式は次のとおりです。

  [[protocol:]//]host1{,host12}[:port1]{,host2:port2}[/service_name][:server][/instance_name][?parameter_name=value{&parameter_name=value}]

  Oracle Databaseリリース19c以降、簡易接続ネーミング構文は拡張されています。簡易接続ネーミングの拡張機能を参照してください。

• フォームのtnsnames.ora構成ファイル・エントリのローカル・ネーミング・パラメータ:

  net_service_name= 
   (DESCRIPTION= 
  (ADDRESS=(protocol_address_information))
     (CONNECT_DATA= 
       (SERVICE_NAME=service_name))) 

• フォームのOracle Net接続記述子:

  "(DESCRIPTION=(ADDRESS=(PROTOCOL=protocol-name) (HOST=host-name) (PORT=port-number))
  (CONNECT_DATA=(SERVICE_NAME=service-name)))"
  

• サイトがLDAPサーバー・ディレクトリ用に構成されているディレクトリ・ネーミングを通じて解決される接続名。

tnsnames.oraなどのネーミング・メソッドやディレクトリ・ネーミングを使用するには、TNS_ADMIN環境変数も設定できます。

TNS_ADMIN環境変数が設定されていない場合に、inst1などのtnsnames.oraエントリを使用するときは、ORACLE_HOME変数を設定する必要があります。また、構成ファイルは$ORACLE_HOME/network/admin ディレクトリに存在する必要があります。この場合、ORACLE_HOME変数は、Oracle Net構成ファイルの検索のみに使用され、クライアント・コード・ライブラリの他のコンポーネント(OCI、NLSなど)は、ORACLE_HOMEの値を使用しません。そのため、TNS_ADMIN環境変数を設定してtnsnames.oraファイルの場所を特定する方が簡単で、推奨されます。

OCIServerAttach()コールで接続文字列としてNULL文字列""を使用する場合、TWO_TASK環境変数をconnect_identifierに設定できます。Windowsオペレーティング・システムでは、TWO_TASKのかわりにLOCAL環境変数を使用します。

同様に、SQL*PlusなどのOCIアプリケーションには、TWO_TASK (WindowsではLOCAL)環境変数をconnect_identifierに設定できます。この環境変数には、通常の接続文字列上で'@'より右側であれば、任意の値を指定できます。

関連項目:

• 接続記述子の詳細は、『Oracle Database Net Services管理者ガイド』の「ネーミング・メソッドの構成」を参照してください

3.4.1Oracle Database接続文字列の接続識別子の例

OCIアプリケーション(SQL*Plusなど)を使用している場合は、次の方法でデータベース接続文字列を指定できます。

Oracle Databaseのlistener.oraファイルに次の記述が含まれる場合:

LISTENER = (ADDRESS_LIST=
 (ADDRESS=(PROTOCOL=tcp)(HOST=server6)(PORT=1573))
)
 
SID_LIST_LISTENER = (SID_LIST= 
 (SID_DESC=(SID_NAME=rdbms3)(GLOBAL_DBNAME=rdbms3.server6.us.alchemy.com)
(ORACLE_HOME=/home/dba/rdbms3/oracle))
)

OCIアプリケーション、接続識別子は次のとおりです。

"server6:1573/rdbms3.server6.us.alchemy.com"

接続識別子は次のように指定することもできます。

"(DESCRIPTION=(ADDRESS=(PROTOCOL=tcp)(HOST=server6)(PORT=1573))(CONNECT_DATA=
(SERVICE_NAME=rdbms3.server6.us.alchemy.com)))"

または、TWO_TASK環境変数を任意の以前の接続識別子に設定し、接続識別子を新規に指定せずに接続することもできます。たとえば、次のようにします。

export TWO_TASK=//server6:1573/rdbms3.server6.us.alchemy.com

TWO_TASK環境変数を次のように指定することもできます。

export TWO_TASK=(DESCRIPTION=(ADDRESS=(PROTOCOL=tcp)(HOST=server6)(PORT=1573))
(CONNECT_DATA=(SERVICE_NAME=rdbms3.server6.us.alchemy.com)))

次に、空の接続識別子を使用してOCIアプリケーションを起動できます。たとえば、SQL*Plusを実行するには、次のようにします。

sqlplus user

接続記述子は、tnsnames.oraファイルにも指定できます。たとえば、tnsnames.oraファイルに次の接続記述子が記載され、

conn_str = (DESCRIPTION=(ADDRESS=(PROTOCOL=tcp)(HOST=server6)(PORT=1573))(CONNECT_DATA=
(SERVICE_NAME=rdbms3.server6.us.alchemy.com)))

tnsnames.oraファイルが/home/webuser/myconfigsディレクトリにある場合、変数TNS_ADMIN (WindowsではLOCAL)を次のように設定できます。

export TNS_ADMIN=/home/webuser/myconfigs

その後、接続識別子conn_strを使用して、SQL*PlusなどのOCIアプリケーションを起動するか、OCI接続を行うことができます。

ノート:

TNS_ADMINには、tnsnames.oraファイルを配置するディレクトリを指定します。TNS_ADMINはtnsnames.oraファイルのフルパスではありません。

前述のtnsnames.oraファイルがインストールが行われたOracleホームの、/network/server6/home/dba/oracle/network/adminディレクトリにある場合、ORACLE_HOME環境変数を次のように設定して、前と同様にSQL*PlusなどのOCIアプリケーションを識別子conn_strを使用して起動できます。

export ORACLE_HOME=/network/server6/home/dba/oracle

最後に、tnsnames.oraがTNS_ADMINまたはORACLE_HOMEにあれば、TWO_TASK環境変数を次のように設定して、接続識別子なしでSQL*PlusなどのOCIアプリケーションを起動できます。

export TWO_TASK=conn_str

3.5 異なるバージョンのタイムゾーン・ファイルで操作するクライアントとサーバー

Oracle Databaseリリース11.2以上では、クライアントとサーバーで異なるバージョンのタイム・ゾーン・ファイルを使用できます。この動作モードはOracle Database 11.2より前のリリースではサポートされていませんでした。

このような混在モードで作業するには、クライアントとサーバーの両方が11.2以上であることが必要です。この項では、このようなモードで作業する場合に発生する問題について説明します。これらの問題を回避するには、クライアントとサーバーで同じバージョンのタイム・ゾーン・ファイルを使用します。

クライアントとサーバーで異なるバージョンのタイムゾーン・ファイルを使用している場合、次の動作が見られます。異なるバージョンのタイムゾーン・ファイルを使用すると、TIMESTAMP WITH TIMEZONE (TSTZ)データ型の値の処理にのみ影響が出ることに注意してください。

• 次に示すOCIの日時および時間隔のAPIでは、入力パラメータがTSTZ型の場合、無条件にエラーが発生します。これは、これらの操作が、データベースと同期していないクライアント上のローカル・タイムゾーン・ファイルに依存するためです。そのような構成で計算を続けると、クライアント層とデータベース層間で計算の一貫性がなくなる可能性があります。

  OCIDateTimeCompare()
  OCIDateTimeConstruct()
  OCIDateTimeConvert()
  OCIDateTimeSubtract()
  OCIIntervalAdd()
  OCIIntervalSubtract()
  OCIIntervalFromTZ()
  OCIDateTimeGetTimeZoneName()
  OCIDateTimeGetTimeZoneOffset()Foot 1
  OCIDateTimeSysTimeStamp()
  

• TSTZ値の取得または変更時に、パフォーマンスが低下します。パフォーマンスの低下は、異なるバージョンのタイムゾーン・ファイルを使用するクライアントとサーバーの補正に、追加の変換が必要であることから生じます。

• より新しいタイムゾーン・ファイルで新規タイムゾーン・リージョンが定義される場合、新規タイムゾーン・リージョンを認識しないバージョンのタイムゾーン・ファイルを持つノードで、新規リージョンに属するTIMESTAMP WITH TIMEZONE値に対してエラーが発生する可能性があります。

TSTZ型属性を含む不透明型またはXMLTypeのインスタンス、あるいはその両方を操作するアプリケーションでは、データ損失を避けるために、クライアントとサーバーで同じバージョンのタイムゾーン・ファイルを使用する必要があります。

関連項目:

タイムゾーン・ファイルとタイムスタンプのタイムゾーン・データによるアップグレードの詳細は、『Oracle Databaseグローバリゼーション・サポート・ガイド』を参照してください

3.6 oraaccess.xmlを使用するOCIクライアント側デプロイメント・パラメータ

このトピックでは、oraaccess.xmlを使用するOCIクライアント側デプロイメント・パラメータについて説明します。

この項には次のトピックが含まれます:

• oraaccess.xmlについて

• oraaccess.xmlで指定されるクライアント側デプロイメント・パラメータについて

• oraaccess.xmlの概要

• oraaccess.xmlでのグローバル・パラメータの指定について

• 接続パラメータのデフォルトの指定について

• 接続文字列レベルでの接続パラメータのオーバーライド

• oraaccess.xml内のOCIセッション・プールの構成について

• ファイル(oraaccess.xml)のプロパティ

3.6.1 oraaccess.xmlについて

Oracle Databaseリリース12c リリース1 (12.1)より、クライアント側構成ファイルのoraaccess.xmlが提供されるようになりました。

このoraaccess.xmlファイルを使用して、選択するOCIパラメータ(これらの一部はプログラム的に各種OCI APIコールで受け入れられます)を構成でき、これにより、OCIをコールするソース・コードを変更せずにデプロイメント中にOCIの動作を変更できるようになります。

oraaccess.xmlファイルの更新は、実行中のクライアントには影響しません。oraaccess.xmlファイルの更新を適用するには、すでに実行中のクライアントを再起動する必要があります。

oraaccess.xmlファイルは、通常およびインスタント・クライアント・インストールのTNS_ADMIN環境変数で指定するディレクトリから読み取られます。これは、通常のクライアント・インストールでTNS_ADMINが設定されていない場合は、UNIXオペレーティング・システムでは$ORACLE_HOME/network/adminディレクトリ、Microsoft Windowsオペレーティング・システムでは%ORACLE_HOME%\NETWORK\ADMINディレクトリになります。

3.6.2 oraaccess.xmlで指定されるクライアント側デプロイメント・パラメータについて

等価のパラメータをsqlnet.oraおよびoraaccess.xmlファイルの両方で設定した場合、oraaccess.xmlファイルの設定の方が、対応するsqlnet.oraファイルの設定より優先されます。

そのような場合、今後は、oraaccess.xmlファイルの設定を使用することをお薦めします。いずれのネットワーク構成の場合でも、oraaccess.xmlファイルではネットワーク・レベルの設定がサポートされていないため、sqlnet.oraファイルがそのまま主ファイルになります。

3.6.3 oraaccess.xmlの概要

oraaccess.xmlファイルの概要について説明します。

oraaccess.xmlファイルには、トップレベル・ノードの<oraaccess>があり、次の3つの要素が続きます。

• <default_parameters> - この要素は、接続間で共有されるデフォルトのパラメータ設定を記述します。これらのデフォルト・パラメータには次のものがあります。

  • グローバル・パラメータのデフォルト - これらのグローバル・パラメータは一度のみ指定でき、そのため、すべての接続に適用され、接続レベルでオーバーライドすることはできません。これらのパラメータは、次のタグを使用して指定します。

    • <events> - 高速アプリケーション通知(FAN)および実行時接続ロード・バランシングに必要なOCI_EVENTSモードのOCI環境を作成します。

    • <result_cache> - OCIクライアント結果キャッシュ・パラメータを設定します。

    • <diag> - OCI障害診断パラメータを設定します。

  • 接続固有のパラメータのデフォルト - 接続パラメータは、特定の接続において別の値に設定できます。ただし、デフォルトにも設定でき、必要に応じて接続文字列ごとにオーバーライドできます。これらのデフォルト値は、以降のすべての接続間で共有されます(ただし、接続レベルでオーバーライドされないかぎり。<config_descriptions>リスト項目で説明されています)。これらのデフォルト値は、次のタグを使用して指定します。

    • <prefetch> - すべての問合せのプリフェッチ行の数を設定します。<rows>パラメータを使用して指定します。

    • <statement_cache> - セッションごとにキャッシュ可能な文の最大数を設定します。<size>パラメータを使用して指定します。

    • <auto tune>: 自動チューニングをオンまたはオフにする<enable>、クライアント・システムで使用可能な物理メモリーがしきい値に達した際に、自動チューニングでこれ以上のメモリーの使用を停止するためのメモリーしきい値を設定する<ram_threshold>、およびOCI自動チューニングでクライアント・プロセスごとに使用可能なメモリー制限値を設定する<memory_target>で構成されます。

    • <fan_subscription_failure_action> - サブスクリプションが失敗した際のアクションをtraceまたはerrorのいずれかの値に設定します。

    • <ons> - FAN通知で使用される各種ONSクライアント側デプロイメント構成パラメータを設定します。

• <config_descriptions> - この要素は、基本的に、1つ以上の接続パラメータが含まれている特定のパラメータ・セット(<parameters>)を持つ名前である構成別名要素(<config_alias>)に関連付けられます。これらの接続パラメータは、<prefetch>、<statement_cache>、<auto_tune>、<fan_subscription_failure_action>および<ons>など、前述の要素<default_parameters>内ものと同じ接続パラメータです。

• <connection_configs> - この要素は、構成別名を使用してアプリケーションで使用される1つ以上の接続文字列と関連付けられるため、複数の接続文字列要素で同一のパラメータ・セットを共有できます。

  1つの接続構成要素(<connection_config>)は、構成別名要素(<config_alias>)を使用して1つの接続文字列要素(<connection_string>)と関連付けられます。

  接続文字列は、構成別名を通じてパラメータ・セットに間接的に関連付けられるため、複数の接続文字列要素を同一のパラメータ・セットで共有できます。

次の項では、これらのクライアント側デプロイメント・パラメータの詳細を説明します。

関連項目:

接続パラメータのデフォルトの指定について

3.6.4 oraaccess.xmlでのグローバル・パラメータの指定について

前述したように、<default_parameters>タグを使用して、各種OCIパラメータのデフォルト値を指定できます。

これらのうち、一部のパラメータは一度のみ指定でき、そのため、すべての接続に適用されます。これらのグローバル・パラメータは、次のタグを使用して記述します。

• <events>

  これにより、高速アプリケーション通知(FAN)および実行時接続ロード・バランシングに必要なOCI_EVENTSモードのOCI環境が作成されます。

  <events>
    true <!--value could be false also -->
  </events> 
  

• <result_cache>

  • <max_rset_rows> - プロセス単位の問合せキャッシュ内の結果セットの最大サイズ(行数)です。sqlnet.oraファイル内のOCI_RESULT_CACHE_MAX_RSET_ROWSと等価です。

  • <max_rset_size> - 最大クライアント結果キャッシュ・サイズです。32,768バイト(32KB)以上のサイズに設定します。sqlnet.oraファイル内のOCI_RESULT_CACHE_MAX_RSET_SIZEと等価です。

  • <max_size> - プロセス単位の問合せキャッシュの最大サイズ(バイト数)です。クライアントで32,768未満にサイズを指定すると、クライアント結果キャッシュ機能が無効になります。sqlnet.oraファイル内のOCI_RESULT_CACHE_MAX_SIZEと等価です。

  <result_cache>
        <max_rset_rows>10</max_rset_rows>
        <max_rset_size>65535</max_rset_size>
        <max_size>65535</max_size>
  </result_cache>
  

  等価のパラメータをsqlnet.oraおよびoraaccess.xmlファイルの両方で設定した場合、oraaccess.xmlファイルの設定の方が、対応するsqlnet.oraファイルの設定より優先されます。

  等価のOCIパラメータ設定のリストは、表3-2を参照してください。

• <diag>

  次の要素を指定できます。

  • <adr_enabled> - 診断を有効化または無効化します。sqlnet.oraファイル内のDIAG_ADR_ENABLEDと等価です。値はTRUEまたはFALSEです。

  • <dde_enabled> - DDEを有効化または無効化します。値はTRUEまたはFALSEです。

  • <adr_base> - 現行のADRCIセッションで使用されるADRベースの場所を指定するシステム依存ディレクトリのパス文字列であるADRベース・ディレクトリを設定します。sqlnet.oraファイル内のADR_BASEと等価です。値は、ADRベース・ディレクトリのディレクトリ・パスです。

  • <sighandler_enabled> - OCIシグナル・ハンドラを有効化または無効化します。値はTRUEまたはFALSEです。

  • <restricted> - フル・ダンプ・ファイルを有効または無効にします。Oracle Databaseクライアントには、重要なエラーが検出された際に診断情報をダンプする機能など、問題を診断するための高度な機能が備えられています。デフォルトでは、これらのダンプは、使用可能な情報の小規模なサブセットに制限されており、アプリケーション・データはダンプされません。ただし、大部分のインストールでは、ダンプ・ファイルに対して安全な場所が構成され、このログのプライバシが確保されます。この場合は、フル・ダンプをオンにすることをお薦めします。これにより、問題の解決速度が大幅に向上します。フル・ダンプを有効にするには、値FALSEを指定します。値はTRUEまたはFALSEです。

  • <trace_events> - トレース・イベント番号および有効にするトレース・レベルを示します。現在、イベント10883のみがサポートされています。使用可能なレベルは5と10です。

  <diag>
     <adr_enabled>false</adr_enabled>
     <dde_enabled>false</dde_enabled>
     <adr_base>/foo/adr</adr_base>
     <sighandler_enabled>false</sighandler_enabled>
     <restricted>true</restricted>
     <trace_events>
       <trace_event>
         <number>10883</number>
         <level>5</level>
       </trace_event>
     </trace_events>
  </diag>
  

  等価のパラメータをsqlnet.oraおよびoraaccess.xmlファイルの両方で設定した場合、oraaccess.xmlファイルの設定の方が、対応するsqlnet.oraファイルの設定より優先されます。

  等価のOCIパラメータ設定のリストは、表3-2を参照してください。

  例3-2 oraaccess.xmlおよびsqlnet.oraでの等価OCIパラメータ設定

  パラメータ・グループ	oraaccess.xmlパラメータ	sqlnet.oraパラメータ
  OCIクライアント結果キャッシュ	<max_rset_rows>	OCI_RESULT_CACHE_MAX_RSET_ROWS
  OCIクライアント結果キャッシュ	<max_rset_size>	OCI_RESULT_CACHE_MAX_RSET_SIZE
  OCIクライアント結果キャッシュ	<max_size>	OCI_RESULT_CACHE_MAX_SIZE
  OCI障害診断	<adr_enabled>	DIAG_ADR_ENABLED
  OCI障害診断	<dde_enabled>	DIAG_DDE_ENABLED
  OCI障害診断	<adr_base>	ADR_BASE

関連項目:

• クライアント結果キャッシュおよびクライアント構成ファイル・パラメータのデプロイメント時設定の詳細は、『Oracle Database開発ガイド』を参照してください

• sqlnet.oraファイルのADR診断パラメータの詳細は、『Oracle Database Net Servicesリファレンス』を参照してください

3.6.5 接続パラメータのデフォルトの指定について

接続間で共有される接続パラメータに設定できるデフォルト値について説明します。

次のように、接続間で共有される接続パラメータを指定できます。

• <prefetch> - SELECT文のプリフェッチ行数を指定します。

  <prefetch>
    <rows>100</rows>
  </prefetch>
  

  このパラメータを適切に設定することで、データベースへのラウンドトリップが減り、アプリケーションのパフォーマンスが向上します。

  これは、OCI_ATTR_PREFETCH_ROWSパラメータをオーバーライドするのみであることに注意してください(アプリケーションで明示的に指定されているかどうか)。アプリケーションでOCI_ATTR_PREFETCH_MEMORYが明示的に指定されている場合は、両方の制約を使用して実際のプリフェッチ行数が決定されます。OCI_ATTR_PREFETCH_MEMORYの制約の等価は、oraaccess.xmlファイルでは指定できません。

  また、SELECT文で特定のデータ型の列がフェッチされる場合は、OCIプリフェッチは無効になる場合があることにも注意してください。OCIプリフェッチの詳細は、「結果のフェッチについて」を参照してください。

• <statement_cache> - セッションごとにキャッシュ可能なOCI文ハンドルの数を指定します。

  <statement_cache>
    <size>100</size>
  </statement_cache>
  

  キャッシュ文ハンドルでは、クライアント側およびサーバー側のCPU使用量とネットワーク・トラフィックを減らすことにより、繰返し実行のパフォーマンスが向上します。

  このパラメータを有効にするには、アプリケーションで文ハンドルの取得と破棄用のOCIStatementPrepare2()およびOCIStatementRelease()コールが使用されるようにする必要があります(等価の旧OCISatementPrepare()およびOCIHandleFree()ではなく)。

• <auto_tune> - OCI自動チューニングを有効化するのに使用します。

  <auto_tune>
    <enable>true</enable>
    <ram_threshold>0.1</ram_threshold><!--percentage -->
    <memory target>2M</memory_target>
  </auto_tune>
  

  自動チューニングを有効化することで、指定したメモリー制約に基づいてOCIで文キャッシュ・サイズが自動的にチューニングされるようにすることができます。これにより、ランタイム・アプリケーションの特性および使用可能なメモリー・リソースに基づく適切な値に文キャッシュ・サイズを動的にチューニングできるようになります。

  自動チューニングOCI文キャッシュには、アプリケーションで文ハンドルの取得と破棄用のOCIStatementPrepare2()およびOCIStatementRelease()コールが使用されるようにする必要があります(等価の旧OCISatementPrepare()およびOCIHandleFree()ではなく)。

• <fan_subscription_failure_action> - FAN通知のサブスクライブの失敗へのOCIの対応方法を決定するのに使用します。

  traceの値では、すべてのFAN通知(FANが有効な場合)のサブスクライブの失敗がトレース・ファイルに記録され、OCIはこの失敗を無視して続行されます。errorの値では、FAN通知のサブスクライブに失敗した場合、OCIからエラーが戻されます。

  <fan>
    <!--only possible values are "trace" and "error" -->
    <subscription_failure_action>
      trace
    </subscription_failure_action>
  </fan>
  

• <ons> - Oracle Notification Service (ONS)パラメータを設定します。

  次の接続パラメータを指定できます。

  • <subscription_wait_timeout> - クライアントがONSサーバーへのサブスクリプションを待機する時間の長さ(秒単位)です。

  • <auto_config> - TRUEまたはFALSEです。TRUEの場合は、このセッションで指定された構成でクライアントがデータベースから受信する自動構成情報が拡張されます。FALSEの場合は、前述のものがオーバーライドされます。

  • <thread_stack_size> - イベント通知スレッド・スタックのバイト・サイズです。

  • <debug> - TRUEまたはFALSEです。デバッグ・モードはオン(TRUE)またはオフ(FALSE)のいずれかです。

  • <wallet_location> - セキュアなONSサブスクリプションのための自動ログイン・ウォレット・ファイルが含まれるディレクトリ。

  • <servers> - ポートおよび接続配分を含むホスト・リストです。

  <ons> 
    <!--values or in seconds -->
    <subscription_wait_timeout>
      5
    </subscription_wait_timeout>
    <auto_config>true</auto_config> <!--boolean -->
    <threadstacksize>100k</threadstacksize>
    <debug>true</debug>
    <wallet_location>/etc/oracle/wallets/</wallet_location>
    <servers>
      <address_list>
         <name>pacific</name>
         <max_connections> 3 <\max_connections>
         <hosts>
           10.228.215.121:25293,
           10.228.215.122:25293
         </hosts>
      </address_list>
      <address_list>
         <name>Europe</name>
         <max_connections>3<\max_connections>
         <hosts>
           myhost1.mydomain.com:25273,
           myhost2.mydomain.com:25298,
           myhost3.mydomain.com:30004
         </hosts>
      </address_list>
    </servers>
  </ons>
  

関連項目:

• <auto_tune>

• <ram_threshold>

• <memory_target>

3.6.6 接続文字列レベルでの接続パラメータのオーバーライド

oraaccess.xmlファイルを使用しても、接続文字列レベルで、まったく同じ一連の接続に特有のパラメータをオーバーライドできます。

これにより、これらの接続に特有のパラメータを各アプリケーションの要件に基づいてオーバーライドできます。

<config_descriptions>タグを使用して、一連の接続に特有のパラメータ(<parameters>)が構成別名(接続に特有のパラメータの特定グループを作成する<config_alias>)に関連付けられるように指定できます。その後は、<connection_configs>を使用して、1つ以上の接続文字列(<connection-string>タグを使用して指定)を<config_alias>に関連付けることができるようになります。これにより、複数の<connection_string>要素で同じ<parameters>セットの共有を可能にする間接レベルを設定できます。

例1

この例は、すべての接続に適用可能なグローバル・パラメータおよび接続パラメータのデフォルト化を示す、非常に単純なoraaccess.xmlファイル構成を示しています。

<?xml version="1.0" encoding="ASCII" ?> 
<!--
     Here is a sample oraaccess.xml.
     This shows defaulting of global and connection parameters 
     across all connections. 
-->
 <oraaccess xmlns="http://xmlns.oracle.com/oci/oraaccess"
  xmlns:oci="http://xmlns.oracle.com/oci/oraaccess"
  schemaLocation="http://xmlns.oracle.com/oci/oraaccess
  http://xmlns.oracle.com/oci/oraaccess.xsd">
  <default_parameters>
    <prefetch>
      <rows>50</rows> 
    </prefetch>
    <statement_cache>
      <size>100</size> 
    </statement_cache>
    <result_cache>
      <max_rset_rows>100</max_rset_rows> 
      <max_rset_size>10K</max_rset_size> 
      <max_size>64M</max_size> 
    </result_cache>
  </default_parameters>
</oraaccess>

例2

この例は、接続レベルでオーバーライドされる接続パラメータを示しています。

<?xml version="1.0" encoding="ASCII" ?> 
<!-- 
        Here is a sample oraaccess.xml. 
        This highlights some connection parameters being
        overridden at the connection level
     --> 
 <oraaccess xmlns="http://xmlns.oracle.com/oci/oraaccess"
  xmlns:oci="http://xmlns.oracle.com/oci/oraaccess"
  schemaLocation="http://xmlns.oracle.com/oci/oraaccess
  http://xmlns.oracle.com/oci/oraaccess.xsd">
  <default_parameters>
    <prefetch>
      <rows>50</rows> 
    </prefetch>
    <statement_cache>
      <size>100</size> 
    </statement_cache>
    <auto_tune>
      <enable>true</enable> 
      <ram_threshold>2.67</ram_threshold> 
      <memory_target>204800</memory_target> 
    </auto_tune>
    <result_cache>
      <max_rset_rows>100</max_rset_rows> 
      <max_rset_size>10K</max_rset_size> 
      <max_size>64M</max_size> 
    </result_cache>
  </default_parameters>
    <!-- 
         Create configuration descriptions, which are  
         groups of connection parameters associated with
         a config_alias. 
    --> 
  <config_descriptions>
    <config_description>
      <config_alias>bar</config_alias> 
      <parameters>
        <prefetch>
          <rows>20</rows> 
        </prefetch>
      </parameters>
    </config_description>
    <config_description>
      <config_alias>foo</config_alias> 
      <parameters>
        <statement_cache>
          <size>15</size> 
        </statement_cache>
      </parameters>
    </config_description>
  </config_descriptions>
  <!--   
         Now map the connection string used by the application 
         with a config_alias.  
  --> 
  <connection_configs>
    <connection_config>
      <connection_string>hr_db</connection_string> 
      <config_alias>foo</config_alias> 
    </connection_config>
    <connection_config>
      <connection_string>finance_db</connection_string> 
      <config_alias>bar</config_alias> 
    </connection_config>
  </connection_configs>
</oraaccess>

例3

この例は、FAN通知の設定を示しています。

<?xml version="1.0" encoding="ASCII" ?> 
   <!--
    Here is a sample for oraaccess.xml for 
    setting up for FAN notifications.
   --> 
  <oraaccess xmlns="http://xmlns.oracle.com/oci/oraaccess"
    xmlns:oci="http://xmlns.oracle.com/oci/oraaccess"
    schemaLocation="http://xmlns.oracle.com/oci/oraaccess
    http://xmlns.oracle.com/oci/oraaccess.xsd">
    <default_parameters>
      <fan>
        <!-- only possible values are "trace" or "error" --> 
        <subscription_failure_action>
          error
        </subscription_failure_action> 
      </fan>
      <ons>
        <subscription_wait_timeout>
          5
        </subscription_wait_timeout> 
        <auto_config>true</auto_config>  
      </ons>
    <events>true</events> 
    </default_parameters>
  </oraaccess>

例4

この例は、手動ONS設定が含まれる、高度なoraaccess.xmlファイル構成の使用例を示しています。手動ONS設定は通常は使用しません。

  <?xml version="1.0" encoding="ASCII" ?> 
    <!-- 
       Here is a sample for oraaccess.xml that highlights
       manual ONS settings.
    --> 
  <oraaccess xmlns="http://xmlns.oracle.com/oci/oraaccess"
    xmlns:oci="http://xmlns.oracle.com/oci/oraaccess"
    schemaLocation="http://xmlns.oracle.com/oci/oraaccess
    http://xmlns.oracle.com/oci/oraaccess.xsd">
    <default_parameters>
      <fan>
       <!-- only possible values are "trace" or "error"  --> 
        <subscription_failure_action>
          error
        </subscription_failure_action> 
      </fan>
      <ons>
        <subscription_wait_timeout>
          5
        </subscription_wait_timeout> 
        <auto_config>true</auto_config>  
        <!--This provides the manual configuration for ONS.
            Note that this functionality should not need to be used
            as auto_config can normally discover this 
            information. --> 
        <servers>
          <address_list>
            <name>pacific</name> 
            <max_connections>3</max_connections> 
            <hosts>10.228.215.121:25293, 10.228.215.122:25293</hosts> 
          </address_list>
          <address_list>
            <name>Europe</name> 
            <max_connections>3</max_connections> 
            <hosts>myhost1.mydomain.com:25273, 
              myhost2.mydomain.com:25298, 
              myhost3.mydomain.com:30004</hosts> 
          </address_list>
        </servers>
      </ons>
      <events>true</events> 
    </default_parameters>
  </oraaccess>

関連項目:

接続文字列レベルで、まったく同じ一連の接続に特有のパラメータをオーバーライドする方法は、「接続パラメータのデフォルトの指定について」を参照してください

3.6.7 oraaccess.xml内のOCIセッション・プールの構成について

Oracle Databaseリリース18c、バージョン18.1以上では、OCIセッション・プールの構成は、oraaccess.xmlクライアント側構成ファイルを使用して設定できます。

OCIセッション・プールはoraaccess.xml構成ファイルに次のパラメータ・セットを指定することで構成されます。これらのパラメータは、デフォルト・パラメータ・セクションまたは構成説明セクションで指定できます。デフォルト・パラメータ・セクションで指定されている場合は、アプリケーション内のすべてのセッション・プールに適用されます。これらの設定により、OCIセッション・プールでOCIセッション・プール設定をオーバーライドできます。

• <session_pool>—セッション・プール・パラメータを設定します。

  • <enable>—これをTRUEに設定すると、セッション・プールの構成が有効になります。これは必須パラメータです。つまり、<session_pool>パラメータが構成されている場合は、<enable>パラメータも構成する必要があります。

• <min_size>—プール内の最小接続数です。デフォルトは0 (ゼロ)です。

• <max_size>—プール内の最大接続数です。これは必須パラメータです。つまり、<session_pool>パラメータが構成されている場合は、<max_size>パラメータも構成する必要があります。

• <increment>—プールの拡張時のプール内の接続数の増加量です。デフォルトは1です。

• <inactivity_timeout>—接続が切断された後、プール内で接続がアイドル状態である最大時間(秒単位)です。デフォルトは0です。つまり、接続がプール内でアイドル状態であることについて制限はありません。

• <max_use_session>—接続を取得し、プールに解放できる最大回数です。デフォルトは0です。つまり、接続の取得とプールへの解放について制限はありません。

• <max_life_time_session>—接続がプール内に作成された後の存続時間(秒単位)です。デフォルトは0です。つまり、接続がプール内に作成された後の接続の存続について制限はありません。

oraaccess.xmlファイルを使用して、必要な接続サービスごとにOCIセッション・プールを構成できます。次の例では、それぞれの構成別名、sales_configおよびhr_configに関連付けられている接続パラメータの2つのグループを示しています。ここで、アプリケーションが使用する各接続文字列は、それぞれの構成別名でマップされているため、2つのOCIセッション・プールが提供されます。

<oraaccess xmlns="http://xmlns.oracle.com/oci/oraaccess"
            xmlns:oci="http://xmlns.oracle.com/oci/oraaccess"
            schemaLocation="http://xmlns.oracle.com/oci/oraaccess
            http://xmlns.oracle.com/oci/oraaccess.xsd">
  <default_parameters>
  </default_parameters>
    <!-- 
         Create configuration descriptions, which are  
         groups of connection parameters associated with
         a config_alias. 
    --> 
  <config_descriptions>
    <config_description>
      <config_alias> sales_config </config_alias> 
      <parameters>
         <session_pool>
            <enable>true</enable> 
            <min_size> 10 </min_size>
            <max_size> 100 </max_size>
            <increment> 5 </increment>
         </session_pool>
      </parameters>
    </config_description>
    <config_description>
      <config_alias> hr_config </config_alias> 
      <parameters>
         <session_pool>
            <enable>true</enable>
            <max_size> 10 </max_size>
         </session_pool>
      </parameters>
    </config_description>
  </config_descriptions>
  <!--   
         Now map the connection string used by the application 
         with a config_alias.  
  --> 
  <connection_configs>
    <connection_config>
      <connection_string>sales.us.acme.com</connection_string> 
      <config_alias>sales_config</config_alias> 
    </connection_config>
    <connection_config>
      <connection_string>hr.us.acme.com</connection_string> 
      <config_alias>hr_config</config_alias> 
    </connection_config>
  </connection_configs>
</oraaccess>

3.6.8 ファイル(oraaccess.xml)のプロパティ

ここでは簡単にするために、oraaccess.xmlファイルの構文に関する一部の一般的な規則を示します。

oraaccess.xsdファイルで指定されるXMLスキーマが、oraaccess構文の最終的な公式の参照になります。

• このファイルの内容では大/小文字が区別され、すべての要素(タグ、パラメータ名)は小文字です。

• たとえば、Comment "<!-- comments -->"というように、パラメータ(ノード)の間にコメントを含めることができます。

• パラメータの順序に関する構文はXMLスキーマoraaccess.xsdファイルを参照してください(このリストの後に記載されているoraaccess.xsdファイルに関する詳細を参照)。

• メモリー・サイズの有効な値および形式は、100、100k、100K、1000Mおよび1121mです。つまり、M、m、K、kの接尾辞または接尾辞なしのいずれかのみを使用できます。Kまたはkはキロバイト、Mはメガバイトを意味します。接尾辞なしの場合は、サイズがバイトであることを意味します。

• <ram_threshold>は、0から100の間の10進数で、パーセント値を示す必要があります。

• 数字を指定する場合、正の符号なし整数のみを使用でき、符号は使用できません。有効な形式は、<statement_cache> <size>100</size> </statement_cache>のようになります。

• 構成別名(<config_alias>foo</config_alias>)では大/小文字が区別されません。

• 文字列パラメータ(<config_alias>など)は引用符で囲みません。

• これらの規則は、すべてスキーマ定義にカプセル化されます。

• OCIで無効なoraaccess.xmlファイルが指定された場合、OCIでエラーがレポートされます。

• oraaccess.xmlファイルをデプロイする前に、OracleでサポートされているXMLスキーマ・ファイルoraaccess.xsdを使用して確認することをお薦めします。このスキーマ・ファイルは、通常のクライアントではORACLE_HOME/rdbms/admin、インスタント・クライアントSDKではinstantclient_12_2/sdk/adminにインストールされています。oraaccess.xmlファイルの変更後、独自の任意のXML検証ツールを使用して検証を行うこともできます。

• サンプルのoraaccess.xmlファイルは、通常のクライアントではORACLE_HOME/rdbms/demoディレクトリ、インスタント・クライアントではinstantclient_12_2/sdk/demoにあります。これらのファイルのパラメータはデモ目的のみで、デプロイ前にアプリケーションの要件に合わせて変更およびテストする必要があります。

3.7 互換性およびアップグレードについて

次の各項では、異なるリリースのOCIクライアントとサーバー間での互換性の問題、OCIライブラリ・ルーチンの変更点およびOCIリリース7.xからこのリリースのOCIへのアプリケーションのアップグレードについて説明します。

• Oracleクライアントとサーバーのクロス・バージョンの互換性

• 静的にリンクされたアプリケーションと動的にリンクされたアプリケーションのバージョンの互換性

• 既存のOCIリリース7アプリケーションのアップグレードについて

• サポートされないOCIルーチン

• サポートされないOCIルーチン

3.7.1 Oracleクライアントとサーバーのクロス・バージョンの互換性

一般的な目安として、Oracleクライアントとサーバーのバージョンは、多数のバージョンと互換性があるクロス・バージョンです。

これは、データベースの古いバージョンと新しいバージョンに接続でき、常にクライアントとサーバーの両方を同時にアップグレードする必要がないことを意味します。

ただし、特定の製品およびユーティリティに、製品またはユーティリティ固有でサポートされる組合せに関する追加制限が課される場合があります。

関連項目:

異なるOracleバージョンのクライアントとサーバーの相互運用性サポート・マトリックスの詳細は、My Oracle Supportのドキュメント207303.1を参照してください。

3.7.2 静的にリンクされたアプリケーションと動的にリンクされたアプリケーションのバージョンの互換性

次に、新規リリースで再リンクする場合の規則を示します。

• 静的にリンクされたOCIアプリケーションの場合:

  静的にリンクされたOCIアプリケーションが、メジャー・リリース番号とマイナー・リリース番号の両方について再リンクする必要があるのは、Oracle Databaseのクライアント側のライブラリ・コードが、アップグレードされたOracleホーム内のエラー・メッセージと互換性がないためです。たとえば、エラー・メッセージが追加パラメータで更新された場合、そのエラー・メッセージは、静的にリンクされたコードとは互換性がなくなります。

• 動的にリンクされたOCIアプリケーションの場合:

  Oracle Database 10g以降のリリースの動的にリンクされたOCIアプリケーションは、再リンクする必要はありません。つまり、Oracle Databaseのクライアント側の動的ライブラリには、以前のバージョンのライブラリに対して上位互換性があります。Oracle Universal Installerによって前のバージョンのライブラリへのシンボリック・リンクが作成され、このシンボリック・リンクが現行バージョンのライブラリに解決されます。したがって、以前のバージョンのOracle Databaseのクライアント側動的ライブラリと動的にリンクされたアプリケーションは、現行バージョンのOracle Databaseのクライアント側ライブラリで動作するために再リンクする必要はありません。

  ノート:

  アプリケーションがランタイム・ライブラリ検索パス(Linuxの-rpathなど)とリンクされている場合、アプリケーションはリンクされているOracle Databaseのクライアント側ライブラリのバージョンでまだ動作する可能性があります。現行バージョンのOracle Databaseのクライアント側ライブラリで動作するためには、再リンクする必要があります。

  関連項目:

  • 互換性およびアップグレードの詳細は、『Oracle Databaseアップグレード・ガイド』 を参照してください

  • 現在サポートされているサーバー・バージョンは、My Oracle Supportのドキュメント207303.1に記載されています

3.7.3 既存のOCIリリース7アプリケーションのアップグレードについて

OCIでは、OCIリリース7以降の多くの機能が大幅に改善されました。

OCIリリース7.3 APIを使用していたアプリケーションは、現行リリースのOracle Databaseに対して通常どおり動作します。これらのアプリケーションは、現行のクライアント・ライブラリにリンクする必要があります。ただし、OCIリリース7.3 APIは非推奨となり、このオプションはOracleの今後のリリースでは使用できなくなりました。

OCIリリース7.xおよびこのリリースのOCIのコールは、同じ文の実行で混在させないかぎり、同一アプリケーションおよび同一トランザクション内で使用できます。このため、既存のOCIバージョン7のアプリケーションを移行する場合は、次の2つの方法があります。

• 現行のOCIクライアントにアップグレードしますが、アプリケーションは修正しません。Oracleリリース7 OCIクライアントから現行リリースのOCIクライアントにアップグレードする場合は、新規バージョンのOCIライブラリにリンクするだけでよく、アプリケーションを再コンパイルする必要はありません。再リンクしたOracle Databaseリリース7のOCIアプリケーションは、現行Oracle Databaseに対して通常どおり動作します。このオプションは非推奨となり、Oracleの今後のリリースでは使用できなくなりました。

• 現行のOCIクライアントにアップグレードして、アプリケーションを修正します。ただし、新しいOCIで提供されるパフォーマンスと拡張性の利点を活用するには、新しいOCIプログラミング・パラダイムを使用できるように既存のアプリケーションを修正し、そのアプリケーションを再作成して現行のOCIライブラリに再リンクし、現行リリースのOracle Databaseに対して実行する必要があります。

現行リリースのOracle Databaseのオブジェクト機能を使用する必要がある場合は、クライアントを現行リリースのOCIにアップグレードする必要があります。

ノート:

デフォルトでは、バージョン7のAPIを使用するアプリケーションをOracle Database 12cに接続できなくなります。このアプリケーションをOracle Database 12cに接続するには、sqlnet.allowed_logon_versionを8に設定する必要があります。

Oracle Database 12cリリース2 (12.2)では、Oracle Databaseによってサポートされる識別子の長さが、30バイトから128バイトに増加しました。このデータベースの変更に伴い、非推奨のV7 API odessp()を使用するOCIアプリケーションは、状況に応じて変更する必要があります。odessp()の引数argnamで、アプリケーションは、長さ128バイト(以前は30バイト)の識別子を格納できる2次元配列を渡す必要があります。

UPI API upidpr()を使用するアプリケーションも、Oracle Database 12cリリース2 (12.2)の長い識別子に基づき、状況に応じて変更する必要があります。upidpr()の引数argument_nameで、アプリケーションは、長さ128バイト(以前は30バイト)の識別子を格納できる2次元配列を渡す必要があります。

関連項目:

「Oracle 7ドキュメント」のOracle7 Server Call Interfaceプログラマーズ・ガイド。

3.7.4 サポートされないOCIルーチン

リリース7.3のOCIコールはサポートされません。表3-3は、7.xのOCIコールおよびサポートされる同等のルーチンを示しています。

表3-3 サポートされなくなったOCI関数

7.xのOCIルーチン	以降のリリースでの等価または類似のOCIルーチン
obindps()、obndra()、obndrn()、obndrv()	OCIBindByName()またはOCIBindByName2()、OCIBindByPos()またはOCIBindByPos2() (ノート: 一部のデータ型には追加のバインド・コールが必要です)
obreak()	OCIBreak()
ocan()	なし
oclose()	ノート: リリース8.x以降では、カーソルは使用されていません。
ocof()、ocon()	OCI_COMMIT_ON_SUCCESSモードでのOCIStmtExecute()
ocom()	OCITransCommit()
odefin()、odefinps()	OCIDefineByPos()またはOCIDefineByPos2() (ノート: 一部のデータ型には追加の定義コールが必要です)
odescr()	ノート: スキーマ・オブジェクトはOCIDescribeAny()で記述されます。通常、記述は、リリース7.xで使用されているように、SQL文の実行後にOCIAttrGet()を文ハンドルでコールすることにより行われます。
odessp()	OCIDescribeAny()
oerhms()	OCIErrorGet()
oexec()、oexn()	OCIStmtExecute()
oexfet()	OCIStmtExecute()、OCIStmtFetch2() (ノート: 結果セット行は暗黙的にプリフェッチできます)
ofen()、ofetch()	OCIStmtFetch2()
oflng()	なし
ogetpi()	OCIStmtGetPieceInfo()
olog()	OCILogon()またはOCILogon2()
ologof()	OCILogoff()
onbclr()、onbset()、onbtst()	ノート: 非ブロック化モードは、OCIAttrSet()またはOCIAttrGet()をサーバー・コンテキスト・ハンドルまたはサービス・コンテキスト・ハンドルでコールすることにより、設定またはチェックすることができます。
oopen()	ノート: リリース8.x以上では、カーソルは使用されていません。
oopt()	なし
oparse()	OCIStmtPrepare2()。ただし、すべてローカル
opinit()	OCIEnvCreate()
orol()	OCITransRollback()
osetpi()	OCIStmtSetPieceInfo()
sqlld2()	SQLSvcCtxGetまたはSQLEnvGet
sqllda()	SQLSvcCtxGetまたはSQLEnvGet
odsc()	ノート: 前述のodescr()を参照してください。
oermsg()	OCIErrorGet()
olon()	OCISessionGet()
orlon()	OCISessionGet()
oname()	ノート: 前述のodescr()を参照してください。
osql3()	ノート: 前述のoparse()を参照してください。
obind()	OCIBindByName()、OCIBindByPos() (ノート: 一部のデータ型には追加のバインド・コールが必要です。)
obindn()	OCIBindByName()、OCIBindByPos() (ノート: 一部のデータ型には追加のバインド・コールが必要です。)
odfinn()	OCIDefineByPos() (ノート: 一部のデータ型には追加の定義コールが必要です。)
odsrbn()	ノート: 表3-3のodescr()を参照してください。
ologon()	OCISessionget()
osql()	ノート: 表3-3のoparse()を参照してください。

関連項目:

• 新規または現行のコールが行われる前後に必要な追加のプログラム・ロジックの詳細は、「OCIプログラミングの基本」参照してください。

3.7.5 サポートされないOCIルーチン

OCIの以前のバージョンで使用可能だったOCIルーチンの一部は、現行リリースではサポートされません。

それらは表3-4に記載されています。

表3-4 サポートされないOCI関数

OCIルーチン	以降のリリースでの等価または類似のOCIルーチン
obind()	OCIBindByName()、OCIBindByPos() (ノート: 一部のデータ型には追加のバインド・コールが必要です。)
obindn()	OCIBindByName()、OCIBindByPos() (ノート: 一部のデータ型には追加のバインド・コールが必要です。)
odfinn()	OCIDefineByPos() (ノート: 一部のデータ型には追加の定義コールが必要です。)
odsrbn()	ノート: 表3-3のodescr()を参照してください。
ologon()	OCILogon()
osql()	ノート: 表3-3のoparse()を参照してください。

3.8 OCIでの障害診断

この節では、以下のトピックについて説明します。

• OCIでの障害診断について

• ADRベースの場所

• ADRCIの使用

• sqlnet.oraを使用したADRの作成の管理および障害診断の無効化

3.8.1 OCIでの障害診断について

OCIの11gリリース1 (11.1)では、障害診断が導入されました。

OCIクライアント上のインシデント(問題の発生)は、ユーザーの介入なしで診断データの形式(ダンプ・ファイルまたはコア・ダンプ・ファイル)で取得されます。リリース11.2.0.1までは、診断データは、インシデントについて作成された自動診断リポジトリ(ADR)サブディレクトリに格納されていました。たとえば、LinuxまたはUNIXアプリケーションがNULLポインタ参照で失敗した場合、コア・ファイルはオペレーティング・システム・ディレクトリではなくADRホーム・ディレクトリ(存在する場合)に書き込まれます。ADRサブディレクトリ構造および出力を処理するためのユーティリティであるADRコマンド・インタプリタ(ADRCI)について、次の各項で説明します。ただし、リリース11.2.0.2からは、診断データは現在のディレクトリに格納されます。

ADRホームは、OCIなどの特定の製品のインスタンスおよび特定のオペレーティング・システム・ユーザーに関するすべての診断データのルート・ディレクトリです。ADRホームは、ADRベースという同一のルート・ディレクトリの下でグループ化されます。

障害診断およびOracle DatabaseのADR構造については、『Oracle Database管理者ガイド』の診断データの管理に関する解説で詳しく説明されています。

3.8.2 ADRベースの場所

ADRベースの位置の決定方法について説明します。

ADRベースの場所は、OCIにより次の順序で決定されます。

1. すべての診断パラメータについて、OCIは最初にoraaccess.xmlファイル内で検索します。これらのパラメータがそこで設定されていない場合、OCIは次にsqlnet.oraファイル(存在する場合)で次のような文を検索します(LinuxまたはUNIX)。

   ADR_BASE=/foo/adr
   

   adr (ディレクトリの名前)が存在し、OCIアプリケーションを実行して同じADRベースを共有するすべてのオペレーティング・システム・ユーザーによって書込み可能である必要があります。fooはパス名を表します。sqlnet.oraの場所は、ディレクトリ$TNS_ADMIN (Windowsの場合は%TNS_ADMIN%)で指定されます。$TNS_ADMINが存在しない場合は、現在のディレクトリが使用されます。ADR_BASEが設定されており、すべてのユーザーが1つのsqlnet.oraを共有する場合、ディレクトリadrが存在しない、またはユーザーによる書込みができないと、OCIは検索を停止します。ADR_BASEが設定されていない場合、OCIは検索を続行し、他の特定のディレクトリの有無をテストします。

   たとえば、sqlnet.oraにエントリADR_BASE=/home/chuck/testが含まれる場合、ADRベースは/home/chuck/test/oradiag_chuckであり、ADRホームは/home/chuck/test/oradiag_chuck/diag/clients/user_chuck/host_4144260688_11のようになります。

2. $ORACLE_BASE (Windowsでは%ORACLE_BASE%)が存在します。この場合、Oracle Universal Installerを使用したデータベースのインストール時にクライアント・サブディレクトリが作成されているため、これが存在します。

   たとえば、$ORACLE_BASEが/home/chuck/obaseである場合、ADRベースは/home/chuck/obaseであり、ADRホームは/home/chuck/obase/diag/clients/user_chuck/host_4144260688_11のようになります。

3. $ORACLE_HOME (Windowsでは%ORACLE_BASE%)が存在します。この場合、Oracle Universal Installerを使用したデータベースのインストール時にクライアント・サブディレクトリが作成されているため、これが存在します。

   たとえば、$ORACLE_HOMEが/ade/chuck_l1/oracleである場合、ADRベースは/ade/chuck_l1/oracle/logであり、ADRホームは/ade/chuck_l1/oracle/log/diag/clients/user_chuck/host_4144260688_11のようになります。

4. オペレーティング・システムのホーム・ディレクトリは、LinuxまたはUNIXでは$HOME、Windowsでは%USERPROFILE%です。LinuxまたはUNIXでは、ユーザーchuckの場所は/home/chuck/oradiag_chuckのようになります。Windowsでは、C:\Documents and Settings\chuckの下にOracleというフォルダが作成されます。

   たとえば、Instant Clientでは、$HOMEが/home/chuckである場合、ADRベースは/home/chuck/oradiag_chuckであり、ADRホームは/home/chuck/oradiag_chuck/diag/clients/user_chuck/host_4144260688_11です。

5. Windowsでは、アプリケーションがサービスとして動作している場合、ホーム・ディレクトリ・オプションはスキップされます。

6. LinuxまたはUNIXオペレーティング・システムの一時ディレクトリは/var/tmpです。

   たとえば、Instant Clientでは、$HOMEが書込み不可である場合、ADRベースは/var/tmp/oradiag_chuckであり、ADRホームは/var/tmp/oradiag_chuck/diag/clients/user_chuck/host_4144260688_11です。

   Windowsオペレーティング・システムの一時ディレクトリは、次の順序で検索されます。

   1. %TMP%

   2. %TEMP%

   3. %USERPROFILE%

   4. Windowsシステム・ディレクトリ

これらのディレクトリの選択肢がいずれも使用不可および書込み不可である場合、ADRベースは作成されず、診断は実行されません。

関連項目:

• Oracle Instant Clientについて

• 『Oracle Database Net Servicesリファレンス・ガイド』

3.8.3 ADRCIの使用

ADRCIは、ADR内の診断データを表示し、インシデントおよび問題に関する情報をOracleサポートが使用できるようzipファイルに圧縮できるコマンドライン・ツールです。

ADRCIは対話式に、またスクリプトから使用できます。問題とは、OCIまたはクライアント内のクリティカル・エラーです。各問題に問題キーが割り当てられます。1つのインシデントは問題の1回の発生を意味し、数字を使用した一意のインシデントIDで識別されます。各インシデントには、属性のセット(ORAエラー番号、エラー・パラメータ値およびその他の情報)である問題キーが割り当てられています。2つのインシデントの問題キーが一致する場合、これらのインシデントの根本的原因は同じです。

次に、LinuxシステムでADRCIを起動し、SHOW BASEコマンドについてHELPコマンドを使用し、SHOW BASEコマンドを-PRODUCT CLIENTオプション(OCIアプリケーションに必要)とともに使用する方法を示します。ADRCIコマンドは大/小文字の区別はありません。ユーザー入力は太字で表示されます。

% adrci
 
ADRCI: Release 12.2.0.0.0 - Development on Wed Dec 2 18:26:29 2015 
Copyright (c) 1982, 2015, Oracle.  All rights reserved. ADR base = "/u01/app/oracle/log"

 
adrci> help show base
 
  Usage: SHOW BASE [-product <product_name>]
 
  Purpose: Show the current ADR base setting.
 
  Options:
    [-product <product_name>]: This option allows users to show the
    given product's ADR Base location. The current registered products are
    "CLIENT" and "ADRCI".
 
  Examples: 
    show base -product client
    show base
 
adrci> show base -product client
ADR base = "/u01/app/oracle/log"

次に、SET BASEコマンドを記述しています。

adrci> help set base
 
  Usage:  SET BASE <base_str> | -product <product_name>
 
  Purpose: Set the ADR base to use in the current ADRCI session.
           If there are valid ADR homes under the base, all homes will
           will be added to the current ADRCI session.
 
  Arguments:
    <base_str>: It is the ADR base directory, which is a system-dependent
    directory path string.
    -product <product_name>: This option allows users to set the 
    given product's ADR Base location. The current registered products are
    "CLIENT" and "ADRCI".
 
  Notes:
    On platforms that use "." to signify current working directory,
    it can be used as base_str.
 
  Example: 
    set base /net/sttttd1/scratch/someone/view_storage/someone_v1/log
    set base -product client
    set base .
 
adrci> quit

ADRCIを起動すると、デフォルトのADRベースはrdbmsサーバーに対するものとなります。$ORACLE_HOMEは"/u01/app/oracle/"に設定されます。

% adrci
 
ADRCI: Release 12.2.0.0.0 - Development on Wed Dec 2 18:26:29 2015
 
Copyright (c) 1982, 2015, Oracle.  All rights reserved.
 
ADR base = "/u01/app/oracle/log"
 adrci>

OCIアプリケーションのインシデントの場合、ベースを次のようにチェックおよび設定する必要があります。

adrci> show base -product client
ADR base is "/u01/app/oracle/log" 
adrci> set base /home/chuck_13/oradiag_chuck

Instant Clientの場合、$ORACLE_HOMEがないため、デフォルトのベースはユーザーのホーム・ディレクトリです。

adrci> show base -product client
ADR base is "/home/chuck_13/oradiag_chuck"
adrci> set base /home/chuck/oradiag_chuck
adrci> show incidents
 
ADR Home = /home/chuck/oradiag_chuck/diag/clients/user_chuck/host_4144260688_11:
*************************************************************************
INCIDENT_ID    PROBLEM_KEY           CREATE_TIME
-------------------------------------------------------------------------
1                     oci 24550 [6]              2015-12-02 17:20:02.803697 -07:00                      
1 rows fetched
 
adrci>

関連項目:

Oracle Instant Clientについて

ADRCIの概要は、『Oracle Databaseユーティリティ』 を参照してください

3.8.4 sqlnet.oraを使用したADRの作成の管理および障害診断の無効化

sqlnet.oraを使用したADRの作成および障害診断の無効化を制御する方法について説明します。

診断能力を無効にするには、sqlnet.oraで次のパラメータを設定し(デフォルトはTRUE)、診断をオフにします。

DIAG_ADR_ENABLED=FALSE
DIAG_DDE_ENABLED=FALSE

OCIシグナル・ハンドラをオフにし、標準オペレーティング・システムの障害処理を再度有効化するには、sqlnet.oraで次のパラメータを設定します。

DIAG_SIGHANDLER_ENABLED=FALSE

前述のように、sqlnet.oraでADR_BASEを使用し、ADRベースの場所を設定します。

Oracle Databaseクライアントには、重要なエラーが検出された際に診断情報をダンプする機能など、問題を診断するための高度な機能が備えられています。デフォルトでは、これらのダンプは、使用可能な情報の小規模なサブセットに制限されており、アプリケーション・データはダンプされません。ただし、大部分のインストールでは、ダンプ・ファイルに対して安全な場所が構成され、このログのプライバシが確保されます。この場合は、フル・ダンプをオンにすることをお薦めします。これにより、問題の解決速度が大幅に向上します。フル・ダンプを有効にするには、Oracle Databaseクライアント・インストールで使用したsqlnet.oraファイルに次の行を追加します。

DIAG_RESTRICTED=FALSE

診断機能が正しく機能していることを確認するには:

1. 最新のクライアント・ライブラリを使用するように、アプリケーションをアップグレードします。
2. アプリケーションを起動します。
3. アプリケーションのTNS_ADMINディレクトリにあるsqlnet.logファイルに、診断機能を起動できなかったこと(通常、これは無効なディレクトリ名または権限が原因です)を示すエラー・メッセージがないか調べます。

関連項目:

• sqlnet.oraでのADRパラメータの設定については、『Oracle Database Net Servicesリファレンス』を参照してください

• ADRの構造に関する詳細は、『Oracle Database Net Services管理者ガイド』を参照してください

---

脚注の説明

脚注 1:

クライアントとサーバーのタイム・ゾーン・ファイルが一致しない(リージョンが同期化されていない)場合は、ORA-01805エラーが戻されます。リージョン・タイム・ゾーン値が同じ(UTCで同じインスタントを示す)場合は、TIME ZONEオフセットが異なっていてもOCI_SUCCESSが戻されます。