1. プログラマーズ・ガイド
  2. OCIに関する高度なトピック

11 OCIに関する高度なトピック

この章では、OCIに関連するより高度なトピックについて説明します。

OCIを使用して、Oracle TimesTen In-Memory DatabaseおよびOracle TimesTen Application-Tier Database Cacheにアクセスできます。

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

関連項目:

TimesTenでのOracle Call Interfaceサポートの詳細は、『Oracle TimesTen In-Memory Database C開発者ガイド』を参照してください。

連続問合せ通知について

連続問合せ通知(CQN)を使用すると、クライアント・アプリケーションがデータベースに問合せを登録し、オブジェクトでのDMLまたはDDL変更に応じて、あるいは問合せに関連付けられた結果セット変更に応じて通知を受信できます。

通知は、DMLトランザクションまたはDDLトランザクションのコミット時にデータベースによって発行されます。

登録時に、アプリケーションは通知ハンドラを指定し、登録する一連の問合せを通知ハンドラに関連付けます。通知ハンドラは、サーバー側のPL/SQLプロシージャでも、クライアント側のC言語のコールバックでもかまいません。登録は、オブジェクト・レベルまたは問合せレベルで作成されます。登録がオブジェクト・レベルにある場合、トランザクションで登録済オブジェクトのいずれかが変更されてコミットされると常に、通知ハンドラが起動されます。登録が問合せレベルにある場合、トランザクションで問合せの結果セットが変わるような変更内容がコミットされると常に、通知ハンドラが起動されますが、変更内容が問合せの結果セットに影響しない場合、通知ハンドラは起動されません。

問合せ変更通知は、OCI_STMT_SELECT、OCI_STMT_BEGIN、OCI_STMT_DECLAREおよびOCI_STMT_CALLといった種類の文に登録できます。

問合せ変更通知では、PLSQLコードにより、SELECT文のみが実行され、SELECT文ごとに登録されるとみなされます。そうではなく、PLSQLコードにSELECT以外の文が含まれると、エラーが発生します。

連続問合せ通知の用途の1つは、データをキャッシュし、そのキャッシュをバックエンド・データベースのためにできるだけ最新の状態で維持する必要がある中間層アプリケーションでの使用です。

通知には次の情報が含まれます。

  • 結果セットが変更された問合せの問合せID。これは、登録が問合せの細分化レベルにあった場合です。

  • 変更されたオブジェクトの名前または変更された行。

  • 操作タイプ(INSERT、UPDATE、DELETE、ALTER TABLE、DROP TABLE)。

  • 変更された行のROWIDと関連するDML操作(INSERT、UPDATE、DELETE)。

  • グローバル・データベース・イベント(STARTUP、SHUTDOWN)。Oracle Real Application Clusters (Oracle RAC)では、データベースは最初のインスタンスの起動時または最後のインスタンスの停止時に通知を送信します。

関連項目:

データベースの起動と停止

データベースの起動および停止に関するトピックについて説明します。

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

OCIデータベースの起動と停止について

OCI関数OCIDBStartup()およびOCIDBShutdown()には、Oracle Databaseを起動および停止するために最小限必要なインタフェースが用意されています。

C言語のプログラムから、OCIDBStartup()をコールする前に、サーバーに接続し、事前認証モードでSYSDBAまたはSYSOPERセッションを開始する必要があります。インスタンスが起動していない場合はこのモードのみを使用でき、インスタンスを起動するためにのみ使用されます。OCIDBStartup()をコールすると、データベースをマウントまたはオープンせずに1つのサーバー・インスタンスが起動します。データベースをマウントまたはオープンするには、事前認証セッションを終了し、通常のSYSDBAまたはSYSOPERセッションを開始し、適切なALTER DATABASE文を実行します。

データベースを停止するには、アクティブなSYSDBAまたはSYSOPERセッションが必要です。OCI_DBSHUTDOWN_ABORT以外のすべてのモードにおいて、OCIDBShutdown()に2つのコールを実行します。1つめのコールは、データベースへのこれ以上の接続を禁止することにより停止を開始し、次に適切なALTER DATABASEコマンドによりデータベースをディスマウントして閉じるためのもので、もう1つのコールは、インスタンスを停止することにより停止を終了させるためのものです。特別な環境においては、データベースをできるかぎり迅速に停止させるために、OCIDBShutdown()をOCI_DBSHUTDOWN_ABORTモードでコールしますが、これはSQL*PlusでのSHUTDOWN ABORTに相当します。

これらの関数は両方とも、サーバーに対する専用接続を必要とします。ディスパッチャを介して共有サーバーに接続されている場合、データベースを起動または停止しようとすると、ORA-106が発生します。

OCIAdmin管理ハンドルCデータ型を使用して、インタフェースを拡張可能にします。OCIAdminは、ハンドル・タイプOCI_HTYPE_ADMINに関連付けられています。OCIAdminパラメータadmhpに値を渡すかどうかは、OCIDBStartup()ではオプションで選択できますが、OCIDBShutdown()では不要です。

関連項目:

OCIでの起動と停止の例

起動するには、SYSOPERまたはSYSDBAとしてOCI_PRELIM_AUTHモードでデータベースに接続する必要があります。ディスパッチャを介して共有サーバーには接続できません。

クライアント側のパラメータ・ファイル(pfile)を使用するには、OCIAttrSet()を使用して管理ハンドルで属性OCI_ATTR_ADMIN_PFILEを設定する必要があります。設定しない場合、サーバー側のパラメータ・ファイル(spfile)が使用されます。後者の場合は、(OCIAdmin *)0を渡します。OCIDBStartup()のコールにより、サーバー上で1つのインスタンスが起動します。

例11-1では、管理ハンドルで設定され、データベース起動操作を実行する、クライアント側のパラメータ・ファイル(pfile)を使用するサンプル・コードを示しています。

停止するには、SYSOPERまたはSYSDBAとしてデータベースに接続する必要があります。ディスパッチャを介して共有サーバーには接続できません。OCI_DBSHUTDOWN_ABORT以外のモードで停止する場合、次の手順を使用します。

  1. OCIDBShutdown()をOCI_DEFAULT、OCI_DBSHUTDOWN_TRANSACTIONAL、OCI_DBSHUTDOWN_TRANSACTIONAL_LOCALまたはOCI_DBSHUTDOWN_IMMEDIATEモードでコールし、これ以上の接続を禁止します。
  2. 必要なALTER DATABASEコマンドを使用し、データベースをクローズしてディスマウントします。
  3. OCIDBShutdown()をOCI_DBSHUTDOWN_FINALモードでコールし、インスタンスを停止します。

例11-1 データベースの起動操作を実行するOCIDBStartup()のコール

...

/*  Example 0 - Startup:  */
OCIAdmin *admhp;
text *mount_stmt = (text *)"ALTER DATABASE MOUNT";
text *open_stmt = (text *)"ALTER DATABASE OPEN";
text *pfile = (text *)"/ade/viewname/oracle/work/t_init1.ora";

/* Start the authentication session */
checkerr(errhp, OCISessionBegin (svchp, errhp, usrhp,
         OCI_CRED_RDBMS, OCI_SYSDBA|OCI_PRELIM_AUTH));

/* Allocate admin handle for OCIDBStartup */
checkerr(errhp, OCIHandleAlloc((void *) envhp, (void **) &admhp,
         (ub4) OCI_HTYPE_ADMIN, (size_t) 0, (void **) 0));

/* Set attribute pfile in the admin handle 
(do not do this if you want to use the spfile) */
checkerr (errhp, OCIAttrSet( (void *) admhp, (ub4) OCI_HTYPE_ADMIN,
          (void *) pfile, (ub4) strlen(pfile),
          (ub4) OCI_ATTR_ADMIN_PFILE, (OCIError *) errhp));

/* Start up in NOMOUNT mode */
  checkerr(errhp, OCIDBStartup(svchp, errhp, admhp, OCI_DEFAULT, 0));
   checkerr(errhp, OCIHandleFree((void *) admhp, (ub4) OCI_HTYPE_ADMIN));

/* End the authentication session */
OCISessionEnd(svchp, errhp, usrhp, (ub4)OCI_DEFAULT);

/* Start the sysdba session */
checkerr(errhp, OCISessionBegin (svchp, errhp, usrhp, OCI_CRED_RDBMS,
         OCI_SYSDBA));

/* Mount the database */
checkerr(errhp, OCIStmtPrepare2(svchp, &stmthp, errhp, mount_stmt, (ub4)
         strlen((char*) mount_stmt),
         (CONST OraText *) 0, (ub4) 0, (ub4) OCI_NTV_SYNTAX, (ub4)
         OCI_DEFAULT));
checkerr(errhp, OCIStmtExecute(svchp, stmthp, errhp, (ub4) 1, (ub4)0,
         (OCISnapshot *) NULL, (OCISnapshot *) NULL, OCI_DEFAULT));
checkerr(errhp, OCIStmtRelease(stmthp, errhp, (OraText *)0, 0, OCI_DEFAULT));

/* Open the database */
checkerr(errhp, OCIStmtPrepare2(svchp, &stmthp, errhp, open_stmt, (ub4)
         strlen((char*) open_stmt),
         (CONST OraText *)0, (ub4)0, (ub4) OCI_NTV_SYNTAX, (ub4) OCI_DEFAULT));
checkerr(errhp, OCIStmtExecute(svchp, stmthp, errhp, (ub4) 1, (ub4)0,
         (OCISnapshot *) NULL, (OCISnapshot *) NULL, OCI_DEFAULT));
checkerr(errhp, OCIStmtRelease(stmthp, errhp, (OraText *)0, 0, OCI_DEFAULT));

/* End the sysdba session */
OCISessionEnd(svchp, errhp, usrhp, (ub4)OCI_DEFAULT);
...

例11-2 OCI_DBSHUTDOWN_FINALモードでのOCIDBShutdown()のコール

/*  Example 1 - Orderly shutdown:  */
...
text *close_stmt = (text *)"ALTER DATABASE CLOSE NORMAL";
text *dismount_stmt = (text *)"ALTER DATABASE DISMOUNT";

/* Start the sysdba session */
checkerr(errhp, OCISessionBegin (svchp, errhp, usrhp, OCI_CRED_RDBMS,
         OCI_SYSDBA));

/* Shutdown in the default mode (transactional, transactional-local,
  immediate would be fine too) */
checkerr(errhp, OCIDBShutdown(svchp, errhp, (OCIAdmin *)0, OCI_DEFAULT));

/* Close the database */
checkerr(errhp, OCIStmtPrepare2(svchp, &stmthp, errhp, close_stmt, (ub4)
         strlen((char*) close_stmt),
         (CONST OraText *)0, (ub4)0, (ub4) OCI_NTV_SYNTAX,
         (ub4) OCI_DEFAULT));
checkerr(errhp, OCIStmtExecute(svchp, stmthp, errhp, (ub4) 1, (ub4)0,
        (OCISnapshot *) NULL,
        (OCISnapshot *) NULL, OCI_DEFAULT));
checkerr(errhp, OCIStmtRelease(stmthp, errhp, (OraText *)0, 0, OCI_DEFAULT));

/* Dismount the database */
checkerr(errhp, OCIStmtPrepare2(svchp, &stmthp, errhp, dismount_stmt,
         (ub4) strlen((char*) dismount_stmt), (CONST OraText *)0, (ub4)0,
         (ub4) OCI_NTV_SYNTAX, (ub4) OCI_DEFAULT));
checkerr(errhp, OCIStmtExecute(svchp, stmthp, errhp, (ub4) 1, (ub4)0,
         (OCISnapshot *) NULL,
         (OCISnapshot *) NULL, OCI_DEFAULT));
checkerr(errhp, OCIStmtRelease(stmthp, errhp, (OraText *)0, 0, OCI_DEFAULT));

/* Final shutdown */
checkerr(errhp, OCIDBShutdown(svchp, errhp, (OCIAdmin *)0,
         OCI_DBSHUTDOWN_FINAL));

/* End the sysdba session */
checkerr(errhp, OCISessionEnd(svchp, errhp, usrhp, (ub4)OCI_DEFAULT));
...

例11-3 OCI_DBSHUTDOWN_ABORTモードでのOCIDBShutdown()のコール

/*  Example 2 - Shutdown using abort:  */
...
/* Start the sysdba session */
...
checkerr(errhp, OCISessionBegin (svchp, errhp, usrhp, OCI_CRED_RDBMS,
         OCI_SYSDBA));

/* Shutdown in the abort mode */
checkerr(errhp, OCIDBShutdown(svchp, errhp, (OCIAdmin *)0,
         OCI_DBSHUTDOWN_ABORT));

/* End the sysdba session */
checkerr(errhp, OCISessionEnd(svchp, errhp, usrhp, (ub4)OCI_DEFAULT));
...

例11-2では、データベースの順序正しい停止操作を実行する管理ハンドルで設定される、クライアント側のパラメータ・ファイル(pfile)を使用するサンプル・コードを示しています。

例11-3では、OCI_DBSHUTDOWN_ABORTモードを使用する停止の例を示しています。

関連項目:

ROWIDの暗黙的フェッチ

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

ROWIDの暗黙的フェッチについて

ROWIDは、データベース内の行のグローバル一意識別子です。ROWIDは行が表に挿入されるときに作成され、行が削除されると破棄されます。

ROWID値には、重要な用途がいくつかあります。これは、表の各行の一意識別子です。また、1行にアクセスする場合に最も高速な手段であり、表の行の格納方法を示すことができます。

SELECT ... FOR UPDATE文におけるROWIDの暗黙的フェッチとは、ROWIDがselect文で名前付きの列のいずれかではない場合でも、クライアント側で取得されるということです。OCIDefineByPos()のpositionパラメータは0 (ゼロ)に設定されます。ROWID疑似列値を取得する場合、次のホスト変数を指定できます。

  • SQLT_CHR (VARCHAR2)

  • SQLT_VCS (VARCHAR)

  • SQLT_STR (NULL文字で終了する文字列)

  • SQLT_LVC(LONG VARCHAR)

  • SQLT_AFC (CHAR)

  • SQLT_AVC (CHARZ)

  • SQLT_VST (OCI文字列)

  • SQLT_RDD (ROWID記述子)

SELECT ... FOR UPDATE文では、更新対象の行を識別し、結果セットの各行をロックします。これは、1行の既存の値に基づいて更新する必要がある場合に役立ちます。その場合は、別のユーザーにより行が変更されないことを確認する必要があります。

ROWIDの値を格納する文字バッファの指定時(SQLT_STR形式で取得する場合など)には、ROWIDを格納するのに十分なメモリーを割り当てます。ROWIDデータ型とUROWIDデータ型の違いを覚えておいてください。ROWIDデータ型に格納できるのは物理ROWIDのみですが、UROWID型には論理ROWID (索引構成表の行の識別子)も格納できます。ROWID型の最長内部長は10バイトですが、UROWIDデータ型の場合は3950バイトです。

動的定義は、modeをOCI_DYNAMIC_FETCHとして設定してOCIDefineByPos()またはOCIDefineByPos2()をコールすることと等価です。動的定義を使用すると、特定の定義ハンドルの属性を追加設定できます。実行時に起動され、取得されるフェッチ済データまたはそのピースを格納するバッファへのポインタを取得する、コールバック関数を指定します。

ROWIDの暗黙的フェッチを使用する前に、文ハンドルで属性OCI_ATTR_FETCH_ROWIDを次のように設定する必要があります。 

OCIAttrSet(stmthp, OCI_HTYPE_STMT, 0, 0 , OCI_ATTR_FETCH_ROWID, errhp);

動的定義は、ROWIDの暗黙的フェッチとは互換性がありません。通常のシナリオの場合、このモードのアプリケーションでは1つの列の各行にバッファを提供できます。つまり、1つの列値がフェッチされるたびにコールバックが呼び出されます。

位置0 (ゼロ)についてOCIDefineByPos()またはOCIDefineByPos2()を使用するこの機能は、データ配列を一度にユーザー・バッファにフェッチし、その各ROWIDを同時に取得することが目的です。この機能では、ROWIDがSELECTを使用した問合せの列のいずれかではなくても、SELECT....FOR UPDATE文によりROWIDのフェッチが可能です。データを1つずつユーザー・バッファにフェッチする場合は、既存のOCI_ATTR_ROWID属性を使用できます。

この機能を使用してROWIDをフェッチする場合、文ハンドルのOCI_ATTR_ROWID属性を同時に使用してROWIDを取得することはできません。特定の文ハンドルに対して一度に使用できるのは1つのみです。

関連項目:

ROWIDの暗黙的フェッチの例

ROWIDの暗黙的フェッチの例を示します。

例11-4のCプログラムのフラグメントを基礎として使用します。

例11-4 ROWIDの暗黙的フェッチ

#include <oci.h>
 
int main()
{
 ...
 text *mySql = (text *) "SELECT emp_name FROM emp FOR UPDATE";
 text rowid[100][15] = {0};
 text empName[100][15] = {0};
 ...
 
 /* Set up the environment, error handle, etc. */
 ...
 
 /* Prepare the statement -  select ... for update. */
 
 
  if (OCIStmtPrepare (select_p, errhp,
                      mySql, strlen(mySql), OCI_NTV_SYNTAX, OCI_DEFAULT))
  {
    printf ("Prepare failed \n");
    return (OCI_ERROR);
  }
 
 /* Set attribute for implicit fetching of ROWIDs on the statement handle. */
 if (OCIAttrSet(select_p, OCI_HTYPE_STMT, 0, 0, OCI_ATTR_FETCH_ROWID, errhp))
 {
   printf ("Unable to set the attribute - OCI_ATTR_FETCH_ROWID \n");
   return OCI_ERROR;
 }
  /* 
   * Define the positions: 0 for getting ROWIDs and other positions 
   * to fetch other columns.
   * Also, get the define conversion done implicitly by fetching 
   * the ROWIDs in the string format. 
   */
 
  if (OCIDefineByPos ( select_p,
                       &defnp0,
                       errhp,
                       0,
                       rowid[0],
                       15,
                       SQLT_STR,
                       (void *) ind,
                       (void *) 0,
                       (void *) 0,
                       OCI_DEFAULT) ||
       OCIDefineByPos(select_p,
                       &defnp1,
                       errhp,
                       1,
                       empName[0],
                       15,
                       SQLT_STR,
                       (void *) 0,
                       (void *) 0,
                       (void *) 0,
                       OCI_DEFAULT)
                       )
  {
    printf ("Failed to define\n");
    return (OCI_ERROR);
  }
 
 
  /* Execute the statement. */
 
 if (errr = OCIStmtExecute(svchp,
                            select_p,
                            errhp,
                            (ub4) 5,
                            (ub4) 0,
                            (OCISnapshot *) NULL,
                            (OCISnapshot *) NULL,
                            (ub4) OCI_DEFAULT))
  {
    if (errr != OCI_NO_DATA) 
       return errr;
  }
 
  printf ("Column 0  \t Column 1\n");
  printf ("_________ \t ________\n");
 
  for (i =0 ;i<5 i++)
   {
     printf("%s \t %s \n", rowid[i], empName[i]);
   }
 
 return OCI_SUCCESS;  
}

暗黙的な結果のOCIサポート

Oracle Database 12cリリース1 (12.1)より、PL/SQLで、ストアド・プロシージャおよび無名PL/SQLブロックから暗黙的に結果(カーソル)を戻すことができるようになりました。OCIStmtGetNextResult()は、暗黙的な結果を取り出し、処理するために提供されています。

例11-5に示すように、PL/SQLはDBMS_SQLパッケージでサブプログラムRETURN_RESULTを指定し、実行された文の結果を戻します。現行のリリースでは、SELECT問合せの結果セットのみ、PL/SQLブロックによって暗黙的に戻すことができます。OCIStmtGetNextResult()は、通常のOCIの定義およびフェッチ・コールを実行して行が取り出されるOCI文ハンドルを戻します。

例11-6は、暗黙的に結果セット(カーソル)をクライアントに戻すPL/SQLストアド・プロシージャを示しています。

例11-7は、クライアントによって送信される無名PL/SQLブロックを使用した同じアプローチを示しています。この例では、アプリケーションで暗黙的な結果機能を使用して、OCIアプリケーションからのSQL文のバッチを実装する方法を示しています。OCIアプリケーションでは、PL/SQL無名ブロックを動的に形成して、複数で可変のSELECT文を実行し、DBMS_SQL.RETURN_RESULTを使用して対応するカーソルを戻すことができます。

例11-8は、OCIStmtGetNextResult()コールを使用してPL/SQLストアド・プロシージャ(例11-6を参照)または無名PL/SQLブロック(例11-7を参照)で戻される暗黙的な結果を取り出し、処理する方法を示すOCIプログラムです。

OCIStmtGetNextResult()は、アプリケーションによって反復的にコールされ、実行されたPL/SQL文からの個別の暗黙的な結果を取り出すことができます。アプリケーションでは各結果セットが順次取り出されますが、任意の結果セットから別個に行をフェッチできます。トップレベルのOCI文ハンドルでは、関連付けられているすべての結果セット文ハンドルが追跡されます。トップレベルのOCI文ハンドルを解放すると、すべての暗黙的な結果セットが自動的に閉じられ、解放されます。

属性OCI_ATTR_IMPLICIT_RESULT_COUNTは、使用可能な暗黙的な結果の数を判断するためにOCI文ハンドルに提供されています。

OCIStmtGetNextResult()のrtypeパラメータは、結果の型を戻します。このリリースでは、型OCI_RESULT_TYPE_SELECTのみがサポートされています。SELECTのResultSetと同様、戻される結果セットの記述メタデータはアクセス可能になります。

ノート:

暗黙的な結果をフェッチするために、次のOCIコードを外部プロシージャで使用することもできます。その場合、OCI_PREP2_IMPL_RESULTS_CLIENTは、モードとしてOCIStmtPrepare2() コールに渡す必要があります。

例11-5 DBMS_SQL RETURN_RESULTサブプログラム

procedure return_result(rc        in out sys_refcursor,
                        to_client in boolean default true);

procedure return_result(rc        in out integer,
                        to_client in boolean default true);

例11-6 結果セット(カーソル)をクライアントに暗黙的に戻すためのPL/SQLストアド・プロシージャ

CREATE PROCEDURE foo AS
  c1 sys_refcursor;
  c2 sys_refcursor;
begin
  open c1 for select * from emp;
  dbms_sql.return_result(c1); --return to client
  -- open 1 more cursor
  open c2 for select * from dept;
  dbms_sql.return_result (c2); --return to client
end;

例11-7 結果セット(カーソル)をクライアントに暗黙的に戻すための無名PL/SQLブロック

declare
  c1 sys_refcursor;
  c2 sys_refcursor;
begin
  open c1 for select * from emp;
  dbms_sql.return_result (c1); --return to client
  -- open 1 more cursor
  open c2 for select * from dept;
  dbms_sql.return_result (c2); --return to client
end;

例11-8 PL/SQLストアド・プロシージャまたは無名ブロックのいずれかによって戻された暗黙的な結果を取り出し、処理するOCIStmtGetNextResult()の使用方法

  OCIStmt *stmthp;
  ub4      rsetcnt;
  void    *result;
  ub4      rtype;
  char    *sql = "begin foo; end;";
  
  /* Prepare and execute the PL/SQL procedure. */
  OCIStmtPrepare2(svchp, &stmthp, errhp, (oratext *)sql, strlen(sql),
                 NULL, 0, OCI_NTV_SYNTAX, OCI_DEFAULT);
  OCIStmtExecute(svchp, stmthp, errhp, 1, 0,
                 (const OCISnapshot *)0,
                 (OCISnapshot *)0, OCI_DEFAULT);
 
  /* Now check if any implicit results are available. */
  OCIAttrGet((void *)stmthp, OCI_HTYPE_STMT, &rsetcnt, 0,
             OCI_ATTR_IMPLICIT_RESULT_COUNT, errhp);
 
  /* Loop and retrieve the implicit result-sets.
   * ResultSets are returned in the same order as in the PL/SQL
   * procedure/block.
   */
  while (OCIStmtGetNextResult(stmthp, errhp, &result, &rtype,
                              OCI_DEFAULT) == OCI_SUCCESS)
  {
    /* Check the type of implicit ResultSet, currently
     * only supported type is OCI_RESULT_TYPE_SELECT
     */
    if (rtype == OCI_RESULT_TYPE_SELECT)
    {
      OCIStmt *rsethp = (OCIStmt *)result;
 
      /* Perform normal OCI actions to define and fetch rows. */
    }
    else
      printf("unknown result type %d\n", rtype);
 
    /* The result set handle should not be freed by the user. */
  }
 
  OCIStmtRelease(stmthp, errhp, NULL, 0, OCI_DEFAULT); /* Releases the statement handle. */

関連項目:

クライアント結果キャッシュ

OCIアプリケーションでは、OCI結果キャッシュを活用するクライアント・メモリーを使用して、繰り返される問合せの応答時間を短縮できます。

関連項目:

OCIクライアント結果キャッシュの使用の詳細は、『Oracle Database開発ガイド』を参照してください

クライアント文キャッシュ自動チューニング

クライアント文キャッシュ自動チューニングに関するトピックについて説明します。

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

クライアント文キャッシュ自動チューニングについて

自動チューニングにより、中間層アプリケーションのOCIクライアント・セッション機能を最適化でき、OCIアプリケーションの再プログラムを必要とすることなく、パフォーマンスを向上できます。

キャッシュ・メモリーの増減などの自動チューニング操作は、定期的なOCIStmtPrepare2()およびOCIStmtRelease()のコール中、暗黙的に行われます。キャッシュ・サイズのチェックが必要な場合は、OCIAttrGet()をサービス・ハンドルにOCI_ATTR_STMTCACHESIZEを設定してコールすると、使用されている現在のキャッシュ・サイズが取得されます。

コーディングされたOCIクライアントの文キャッシュ・サイズ設定が最適ではなくなることもあります。たとえば、これはSQL文の別のワーキング・セットを発生させる原因となるワークロードの変更に伴い発生することがあります。サイズが小さすぎると、ネットワーク・アクティビティが過剰になり、サーバーでの解析量が増大します。サイズが大きすぎると、使用されるメモリー量が超過します。クライアント側のアプリケーションが、このキャッシュ・サイズを常に最適に維持することは困難です。

自動チューニングにより、OCIの文キャッシュ・サイズが定期的に自動で再構成されます。自動チューニングは、この潜在的なパフォーマンス問題を解決するためにOCI文キャッシュを再構成するオプションを提供するデプロイメント時間設定を指定することで行われます。

これらの設定は、OCI機能のユーザー構成の手動設定をオーバーライドするクライアントのoraaccess.xmlファイル内の接続文字列ベースのデプロイメント設定として提供されています。

関連項目:

クライアント文キャッシュ自動チューニングの利点

自動チューニング文キャッシュのさらに具体的な利点は、文キャッシュ・サイズを透過的に検出、監視および調整して、パフォーマンスを向上またはメモリー使用量を減少させることです。

開発者およびDBAが、OCIクライアント・アプリケーションに自動チューニングを使用するには次の利点があります。

  • 文キャッシュなど、システムの各部分のパフォーマンスの問題を診断および修正するのに必要な時間や労力を減らします

  • パフォーマンスを向上するためにこのOCI機能の構成に必要な手動変更を最小化します。通常、このような手動変更では異なる構成パラメータでアプリケーションを1回以上再起動する必要があるため、クライアントの高可用性がさらに低下することになります。

  • すべてのOCIアプリケーションに対し、アプリケーションを変更せずにすぐにそのままパフォーマンスを向上するための1つの解決策となります

  • OCIアプリケーションをカスタム実装する(エラーを発生させる可能性がある)必要がなく、OCIアプリケーションを自動チューニングしてパフォーマンスおよびメモリー使用量を最適化できます。この場合、自動チューニングは、OCIクライアント側文キャッシュ・サイズの内部自動チューニングのみに制限されます。

クライアント文キャッシュ自動チューニングのパラメータ

次に示すoraccess.xml内の接続に特有のパラメータは、デフォルトの接続に特有のパラメータを使用して、構成別名ごとに、またはすべての接続文字列全体に対して設定できます。

クライアントのoraaccess.xml構成ファイルで指定する値は、プログラム設定をオーバーライドします。

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

関連項目:

デフォルトの接続に特有のパラメータを使用して、構成別名ごとに、またはすべての接続文字列全体に対して設定する方法の詳細は、「接続パラメータのデフォルトの指定について」を参照してください

<statement_cache>

このパラメータはオプションで、文キャッシュ・チューニング可能コンポーネントの制限を設定します。 

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

この制限は、セッションごとにキャッシュ可能な文の最大数です。自動チューニングが有効かどうかに関係なく、oraaccess.xml内のこの設定は、OCI文キャッシュ・サイズのプログラム設定をオーバーライドします。

自動チューニングが有効な場合、この設定は文キャッシュ・サイズの上限値となり、動的にチューニングされます。

セッションで、OCIStmtPrepare2()およびOCIStmtRelease()における文キャッシュAPIを使用していない場合、この設定は無視されます。

デフォルト値は次のとおりです。

  • 自動チューニングが有効な場合、文キャッシュは動的にチューニングされ、初期の文キャッシュ・サイズは100文に設定されます。

  • 自動チューニングが無効な場合、この設定は、文キャッシュ・サイズのデプロイメント設定として機能し、プログラム設定をオーバーライドします。

関連項目:

<auto_tune>

このセクションでは、自動チューニングのパラメータを指定します。

OCIセッションで、OCIStmtPrepare2()またはOCIStmtRelease()における文キャッシュAPIを使用していない場合、そのセッションでは自動チューニングのパラメータは無視されます。一部のセッションまたは接続においては自動チューニングが有効で、別のセッションまたは接続においては無効であるようなプロセスでも有効です。

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

関連項目:

<enable>true</enable>

このパラメータは、自動チューニングをオンまたはオフにします。

デフォルトでは、自動チューニングはオフ(FALSE)または無効です。 

<auto_tune>
  <enable>true</enable>
</auto_tune>

自動チューニングは内部のデフォルト設定ととも有効化されます。

関連項目:

内部のデフォルト設定とともに有効化される自動チューニングの詳細は、「<statement_cache>」を参照してください

<ram_threshold>

このパラメータは省略可能です。 

<auto_tune>
   <enable>true</enable>
   <ram_threshold>0.1</ram_threshold>
</auto_tune>

デフォルト値は0.01%です。搭載されているRAMに対するパーセンテージとして指定します。この設定を共有するプロセスの自動チューニング・セッション間で使用可能な合計メモリーを指定します。この設定は、プロセスごとまたは接続文字列別名ごとに指定できます。

接続文字列別名ごとに指定すると、クライアント・プロセスで使用される自動チューニングの合計メモリーが増大します。

このため、oraaccess.xmlファイルの<default_parameters>セクションで自動チューニングの制限値を指定することをお薦めします。これにより、クライアント・プロセスのすべてのセッションに対して共通のメモリー・プールを確保します。

自動チューニングで制限値を小さくすると使用されるRAMも減少しますが、システムで実行されている他のプログラムのパフォーマンスが低下する可能性が増大します。

このパラメータは、<auto_tune></auto_tune>デプロイメント設定内で指定する必要があります。

関連項目:

oraaccess.xmlについて

<memory_target>

このパラメータは省略可能です。

<auto_tune>
  <enable>true</enable>
  <memory_target>40M</memory_target>
</auto_tune>

バイト単位で指定します。デフォルトでは未定義です。この設定を共有するプロセスの自動チューニング・セッション間で使用可能な合計メモリーを指定します。この設定は、プロセスごとまたは接続文字列別名ごとに指定できます。

接続文字列別名ごとに指定すると、クライアント・プロセスで使用される自動チューニングの合計メモリーが増大します。

このため、oraaccess.xmlファイルの<default_parameters>セクションで自動チューニングの制限値を指定することをお薦めします。これにより、クライアント・プロセスのすべてのセッションに対して共通のメモリー・プールを確保します。

このパラメータは、<auto_tune></auto_tune>デプロイメント設定内で指定する必要があります。

このパラメータを使用すると、システムに搭載されているRAMに関係なく、自動チューニングにおいて一定量の制限値メモリーが使用されます。

指定していない場合、自動チューニングのメモリーの制限値は、<ram_threshold>パラメータ設定に基づいて決定されます。

<ram_threshold>と<memory_target>の両方のパラメータを指定すると、2つのパラメータのうち小さい方が制限値として有効になります。

関連項目:

oraaccess.xmlについて

接続に特有の自動チューニング・パラメータの比較

すべての自動チューニング・パラメータの比較について説明します。

表11-1は、接続に特有の自動チューニング・パラメータの比較を示しています。

表11-1 接続に特有の自動チューニング・パラメータの比較

パラメータ 設定とセマンティクス 自動チューニングまたはデプロイメント設定について

<statement_cache>

オプションの設定です。

セッションごとのキャッシュ・サイズです。

自動チューニングが有効な場合(「OCIクライアント自動チューニングの有効化または無効化」を参照)、これは各セッションにおける文キャッシュ・サイズの上限値となり、自動チューニングによりチューニングされます。

それ以外の場合は、文キャッシュのデプロイメント設定を参照します。

<auto_tune>

オプションの設定です。

自動チューニングを使用するには、このパラメータを指定します。NULLの接続文字列を指定する場合、この接続文字列を使用するすべての接続、またはすべての接続に適用されます。

自動チューニングのみに関連します

<ram_threshold>0.1</ram_threshold>

オプションの設定です。

クライアントまたは中間層システムに搭載されているRAMに基づいて、パーセンテージ設定をメモリー値に変換します。

これは、クライアント・プロセス内の自動チューニングで使用されるメモリーの上限値です。

搭載されているRAMが8GBの場合、このパラメータを指定しないと、セッション間で800KBのメモリーが割り当てられます。

各接続で自動チューニングのパラメータを独自に設定している可能性があるため、これらの値は構成設定に基づいて全プロセスで増大することがあります。このため、oraaccess.xmlファイルの<default_parameters>セクションでこのパラメータを指定することをお薦めします。構文の説明は、「ファイル(oraaccess.xml)のプロパティ」を参照してください。

自動チューニングのみに関連します。自動チューニングが無効な場合、このパラメータ設定は無視されます。このパラメータは、<auto_tune></auto_tune>デプロイメント設定内で指定する必要があります。

<memory_target>1048576</memory_target>

オプションの設定です。

これは、クライアント・プロセス内の自動チューニングで使用されるメモリーの上限値です。

各接続で自動チューニングのパラメータを独自に設定している可能性があるため、これらの値は構成設定に基づいて全プロセスで増大することがあります。このため、oraaccess.xmlファイルの<default_parameters>セクションでこのパラメータを指定することをお薦めします。

構文の説明は、「ファイル(oraaccess.xml)のプロパティ」を参照してください。

値はバイト単位です。1,048,576バイトが1MBです。

自動チューニングのみに関連します。自動チューニングが無効な場合、このパラメータ設定は無視されます。このパラメータは、<auto_tune></auto_tune>デプロイメント設定内で指定する必要があります。

クライアント文キャッシュ自動チューニングの使用例

次は、接続に特有のパラメータでもある、クライアント文キャッシュの自動チューニング・パラメータの使用方法と対話を示す使用例です。

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

プログラムの文キャッシュ・サイズはこの設定で置換されます。自動チューニングは無効になり、キャッシュはLRUごとに管理されます。この場合、アプリケーションの開発者はOCIアプリケーションの文プリフェッチのプログラム設定をオーバーライドする必要がないとみなしています。

<auto_tune>
  <enable>true</enable>
</auto_tune>

自動チューニングは内部のデフォルト設定ととも有効化されます。

<statement_cache>
  <size>100</size>
</statement_cache>
<auto_tune>
  <enable>true</enable>
  <memory_target>40M</memory_target>
</auto_tune>

100に設定したこの文キャッシュのデプロイメント設定によってプログラムの文キャッシュ・サイズは置換され、また、自動チューニングが有効なため、文キャッシュは自動チューニングされます。メモリーのターゲット設定は、自動チューニングが有効なために有効になります。

自動チューニングでは、メモリー・ターゲット周辺で使用される合計文キャッシュ・メモリーを常に制限しようと試みます。メモリー・ターゲットが指定されていない場合は、搭載されている合計RAMのパーセンテージに基づいて決定されます。

この場合、メモリーの制限値は指定したメモリー・ターゲット値です。

関連項目:

内部のデフォルト設定とともに有効化される自動チューニングの詳細は、「<statement_cache>」を参照してください

OCIクライアント自動チューニングの有効化または無効化

OCIクライアントの自動チューニングを有効および無効にする条件について説明します。

次の条件によって、OCIクライアントの自動チューニングが有効化または無効化されます。

  • 自動チューニングは、クライアントのoraaccess.xmlに<auto_tune>セクションを追加し、TRUE (<enable>true</enable>)に指定した場合に有効になります。

  • 自動チューニングはデフォルトで、またはoraaccess.xmlの<auto_tune>セクションでFALSE (<enable>false</enable>)に設定した場合に無効になります。

クライアント文キャッシュの自動チューニング使用のガイドライン

自動チューニング・パラメータを設定する際に使用するガイドラインについて説明します。

次は、自動チューニング・パラメータを設定する際に使用するガイドラインの一部です。

  • クライアントの応答、メモリー割当てまたはクライアントのCPUのいずれかが高く、OCIアプリケーションを再構築せずにパフォーマンスを向上させたい場合、<auto_tune>設定またはデプロイメント<statement_cache>設定を使用できます。また、自動チューニングにより、クライアントとサーバーの間で転送されるネットワーク・バイト数が減少する場合もあります。

  • AWRまたはADDMで大量の解析がレポートされ、文キャッシュ・サイズをプログラムで変更できないか、または変更したくない場合、文キャッシュの自動チューニングを指定するか、あるいはデプロイメント文キャッシュ設定の<statement_cache>を使用できます。

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

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

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

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ディレクトリになります。

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

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

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

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>)と関連付けられます。

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

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

関連項目:

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

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パラメータ設定のリストは、表11-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パラメータ設定のリストは、表11-2を参照してください。

    例11-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

関連項目:

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

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

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

  • <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>

関連項目:

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

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>

関連項目:

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

ファイル(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にあります。これらのファイルのパラメータはデモ目的のみで、デプロイ前にアプリケーションの要件に合わせて変更およびテストする必要があります。

OCIでの障害診断

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

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管理者ガイド』の診断データの管理に関する解説で詳しく説明されています。

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ベースは作成されず、診断は実行されません。

関連項目:

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>

関連項目:

OCI Instant Clientについて

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

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ファイルに、診断機能を起動できなかったこと(通常、これは無効なディレクトリ名または権限が原因です)を示すエラー・メッセージがないか調べます。

関連項目:

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

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グローバリゼーション・サポート・ガイド』を参照してください

プラガブル・データベースのサポート

マルチテナント・アーキテクチャにより、Oracle Databaseにスキーマ、スキーマ・オブジェクト、および非スキーマ・オブジェクトのポータブル・コレクションを含めることができ、これらはOracleクライアントに個別のデータベースとして表示されます。

マルチテナント・コンテナ・データベース(CDB)は、1つ以上のユーザー作成のプラガブル・データベース(PDB)を含むOracle Databaseです。

OCIクライアントは、関連するPDBにプラガブル・データベースが適切に設定されているサービスを使用してそのPDBに接続できます。

通常、OCIコールはプラガブル・データベースか通常のデータベースのいずれかに接続されているかに関係なく同様に動作します。CDBについて特別な考慮が必要なOCIコールおよび機能を次の各項で説明します。

関連項目:

PDBおよび様々なPDBに接続するサービスの構成の詳細は、Oracle Database管理者ガイドを参照してください。

マルチテナント・コンテナ・データベース(CDB)が含まれるOCI APIコールの一般的な拡張機能

これらの拡張機能は、Oracle Database 12cリリース2 (12.2)以上で削除された制限の結果です。

次の拡張機能は、Oracle Database 12cリリース2 (12.2)以上で削除された制限の結果です。

  • クライアント結果キャッシュは、プラガブル・データベースへの接続とともに動作します。

ALTER SESSION SET CONTAINERのOCI拡張機能

ALTER SESSION SET CONTAINER文の使用に関する一部のOCI制限は削除されました。

これらの操作を実行するには、クライアントがOracle Databaseリリース12cリリース2 (12.2)である必要があります。次の操作のいずれかが試行されると、古いバージョンのクライアントではエラーが戻されます。

  • ALTER SESSION SET CONTAINER文では、OCIのTIMESTAMP WITH TIMEZONEまたはTIMESTAMP WITH LOCAL TIMEZONEデータ型を使用するアプリケーションがサポートされます。異なるデータベース・タイムゾーン設定または異なるデータベース・タイムゾーン・ファイル・バージョン設定を持つプラガブル・データベース間でアプリケーションの切替えが発生しても、これらの型のセマンティクスは維持されます。

  • ALTER SESSION SET CONTAINER文では、文字セットが異なる2つのプラガブル・データベース間でOCI接続を切り替えるこのコマンドの使用がサポートされます。

マルチテナント・コンテナ・データベース(CDB)が含まれるOCI APIコールの一般的な制限

一般的な制限事項について説明します。

  • CDB$ROOT以外のコンテナに接続されている場合、OCI_PRELIM_AUTHモードでログインしようとすると、ORA-24542エラーが発生します。

  • CDB$ROOT以外のコンテナに接続されている場合、OCIDBStartup()を発行しようとすると、ORA-24543エラーが発生します。

  • CDB$ROOT以外のコンテナに接続されている場合、OCIDBShutdown() を発行しようとすると、ORA-24543エラーが発生します。CDB$ROOTに接続されている場合にOCIDBShutdown()を発行すると、インスタンス全体が停止します。

  • OCI連続問合せ通知(CQN)は、CDBではサポートされていません。

  • リリース12.1 (またはそれ以上)より古いクライアント・ライブラリにリンクされている、およびプラガブル・データベースに接続されているOCIアプリケーションでは、通常(共通以外)のユーザーとして接続した場合、高速アプリケーション通知(FAN)高可用性(HA)機能は利用できません。回避策として、そのようなアプリケーションは共通ユーザーとして接続します。この制限は、リリース12.1以上のOCIクライアントには存在しません。

関連項目:

ALTER SESSION SET CONTAINERが含まれるOCIコールの制限

特定の制限事項について説明します。

ALTER SESSION SET CONTAINER文を使用して、1つのプラガブル・データベースから別のプラガブル・データベースへのOCI接続を切り替えることができます。ただし、ALTER SESSION SET CONTAINER文を使用してプラガブル・データベース間の切替えを行うアプリケーションでは、次に示すように使用方法がOCI制限と一貫していることを確認する必要があります。

  • ALTER SESSION SET CONTAINER文は、OCI移行可能セッション(ログイン中にOCI_MIGRATEモードで作成されたセッションなど)には使用できず、この組合せではORA-65135エラーが発生します。

  • ALTER SESSION SET CONTAINER文はOCI接続プール(古いOCI接続プールAPI)にはサポートされておらず、この組合せではORA-65135エラーが発生します。

  • ALTER SESSION SET CONTAINER文は、OCIセッションの切替え(複数のOCIユーザー・ハンドルで同じOCIサーバー・ハンドルを共有)ではサポートされていません。

  • クライアントが最初にEXTENDED MAX_STRING_SIZE設定でコンテナに接続された後、同じセッション内で、STANDARD MAX_STRING_SIZE設定で別のコンテナに切り替えられた(ALTER SESSION SET CONTAINER文を使用して)場合、4000バイトを超えるバインド変数を使用しようとすると後続のOCIStmtExecute()コールでORA-14697エラーが発生します。

  • 実行されたものとは異なるコンテナのコンテキスト内で、OCIStmtFetch()またはOCIStmtFetch2()を使用して、OCI文ハンドルからのフェッチを試行すると、ORA-65108エラーが発生します。

  • ALTER SESSION SET CONTAINER文をOCIで実行する場合、OCIクライアント結果キャッシュは無効になります。

  • 高速アプリケーション通知(FAN)および実行時接続ロード・バランシング通知は、ALTER SESSION SET CONTAINER文を使用してプラガブル・データベース間の接続の切替えが行われるアプリケーションにはサポートされていません。

  • ALTER SESSION SET CONTAINER文は、現在のトランザクションが存在する場合は読取り専用に設定するため、OCIトランザクション・コール(OCITransStart()、OCITransDetach()、OCITransCommit()、OCITransRollback()、OCITransPrepare()、OCITransMultiPrepare()およびOCITransForget())を実行しようとするといずれも新しいコンテナでエラーが発生します。これらのコールを発行するには、元のコンテナに切り替える必要があります。

  • OCISubscriptionUnRegister()コールが、誤ったコンテナ(対応するOCISubscriptionRegister()コールが実行されたものとは異なるコンテナ)のコンテキスト内で試行される場合、ORA-24950が戻されます。

  • OCI_PTYPE_DATABASEを含んだOCIDescribeAny()コールでは、接続先のデータベースが記述されます。ALTER SESSION SET CONTAINER文の実行後、アプリケーションで現在のデータベースの記述の確認が求められる場合は、OCIDescribeAny()コールを再発行する必要があります。

  • 異なるコンテナからのオブジェクトを操作するのに使用されるOCI任意データ、コレクションまたはオブジェクト関数へのコールはサポートされていません。

  • OCIObjectFlush()コールは、OCIObjectNew()コールを使用してオブジェクト・インスタンスが作成されたコンテナでのみサポートされます。

  • OCIObjectFlush()は、ALTER SESSION SET CONTAINER文を使用してコンテナを切り替える前に呼び出すことをお薦めします。OCIObjectFlush()コールは、いずれのトランザクションも開始されていない場合、トランザクションを開始することに注意してください。

  • コンテナの切替え後に実行されたOCIObjectFlush()は、トランザクションが同じセッションによって別のコンテナですでに開始されている場合(暗黙的なDMLの結果として、またはOCIObjectFlush()コールの結果として)、エラーを戻すことがあります。

  • OCIObjectFlush()コールは、OCIObjectFlush()コールが発行されたコンテナのコンテキスト内で使用済となったオブジェクトのみをフラッシュします。

  • バージョンのセッション属性は、ALTER SESSION SET CONTAINER文で変更することがあります。アプリケーションでこれらの属性がキャッシュされる場合、これらの設定はALTER SESSION SET CONTAINER文の後、同じでなくなる可能性があります。OCIAttrGet()コールで取得可能な属性、およびALTER SESSION SET CONTAINER文で変更する可能性がある属性の例を次に示します。

関連項目:

ALTER SESSION SWITCH CONTAINER SWITCH SERVICEが含まれるOCIコールの制限

ALTER SESSION SWITCH CONTAINER SWITCH SERVICE文によるOCIコールの制限について説明します。

Oracle Database 12cリリース2 (12.2)以上では、ALTER SESSION SWITCH CONTAINER SWITCH SERVICE文が追加されたため、元のサービスに接続する場合とは異なる方法で新しいサービスを構成すると、サービス属性が変更される可能性があります。ただし、OCIは、この文による新しい設定に基づいてその処理を変更することはなく、かわりに、元のサービスに接続する場合と同じように元の設定を使用し続けます。たとえば、FANのオン/オフ設定やTAFのオン/オフ設定などは、元のサービスに最初に接続した場合と同じままです。ALTER SESSION SWITCH CONTAINER SWITCH SERVICE文の通常の使用例は、切替え後に同じアプリケーションが使用されるマルチテナント環境内に存在するため、これは切替え後に適切な動作であると考えられます。

シャードを使用するためのOCIインタフェースについて

Oracle Shardingを使用するためのOCIインタフェースについて説明します。

シャードは、各データベースがデータの一部を格納するデータベース・セットの場所です。各データベースに格納されたデータの一部は、チャンクのセットによって表され、各チャンクはデータの特定の範囲に関連付けられます。

チャンクを対象に読取りまたは書込みを行う要求を作成するには、接続開始ステップでそのチャンクを格納している適切なデータベース(シャード)にアプリケーションをルーティングする必要があります。このルーティングを行うには、データ・キーを使用します。データ・キーにより、特定のチャンクへのルーティング(シャーディング・キーを指定)またはチャンクのグループへのルーティング(スーパー・シャーディング・キーを指定)が可能になります。操作対象のチャンクを含む適切なシャードに接続するためには、アプリケーションでキーを指定してから、シャードされたOracle Databaseへの接続(スタンドアロン接続またはOCIセッション・プールから取得された接続)を取得する必要があります。OCIセッション・プールでは、プールから接続をチェックアウトする前にデータ・キーを指定する必要があります。

OCIセッション・プールおよびスタンドアロン接続の場合、シャーディング・キーおよびシャード・グループ・キーを構成して基礎となる接続でセッションを取得するステップは、次のとおりです。

  1. シャーディング・キー記述子を割り当てるため、OCIDescriptorAlloc()をコールし、シャーディング・キーを構成するためにOCI_DTYPE_SHARDING_KEYとして記述子型パラメータを指定します。

    1. シャーディング・キーのすべての列を追加するため、必要な回数だけOCIShardingKeyColumnAdd()をコールし、完全なシャーディング・キーを構成します。

    2. OCIAttrSet()をコールしてOCI_ATTR_SHARDING_KEY属性を指定し、認証ハンドルにシャーディング・キーを設定します。

  2. シャード・グループ・キー記述子を割り当てるため、OCIDescriptorAlloc()をコールし、シャード・グループ・キーを構成するためにOCI_DTYPE_SHARDING_KEYとして記述子型パラメータを指定します。

    1. シャーディング・キーのすべてのグループ列を追加するため、必要な回数だけOCIShardingKeyColumnAdd()をコールし、完全なシャード・グループ・キーを構成します。

    2. OCIAttrSet()をコールしてOCI_ATTR_SUPER_SHARDING_KEY属性を指定し、認証ハンドルにシャード・グループ・キーを設定します。

  3. シャーディング・キーおよびシャード・グループ・キー情報が含まれる前のステップの初期化済認証ハンドルを使用してOCISessionGet()をコールし、シャーディング・キーで指定されたシャードおよびチャンクと、シャード・グループ・キーで指定されたチャンクのグループに対するデータベース接続を取得します。

カスタム・プールの場合、シャーディング・キーおよびシャード・グループ・キーを構成してプールから接続をチェックアウトするステップは、次のとおりです。

  1. カスタム・プールに既存の接続がない場合、直接ステップ7に進みます。それ以外の場合、次のステップを実行します。

  2. シャーディング・キー記述子を割り当てるため、OCIDescriptorAlloc()をコールし、シャーディング・キーを構成するためにOCI_DTYPE_SHARDING_KEYとして記述子型パラメータを指定します。シャーディング・キーのすべての列を追加するため、必要な回数だけOCIShardingKeyColumnAdd()をコールし、完全なシャーディング・キーを構成します。

  3. シャード・グループ・キー記述子を割り当てるため、OCIDescriptorAlloc()をコールし、シャード・グループ・キーを構成するためにOCI_DTYPE_SHARDING_KEYとして記述子型パラメータを指定します。シャーディング・キーのすべてのグループ列を追加するため、必要な回数だけOCIShardingKeyColumnAdd()をコールし、完全なシャード・グループ・キーを構成します。

  4. シャーディング・キー、スーパー・シャーディング・キー記述子および接続文字列を使用してOCIShardInstancesGet()をコールし、指定したシャーディング・キー記述子とスーパー・シャーディング・キー記述子に応じた目的のチャンクが含まれる1つ以上のインスタンス名を戻します。

  5. カスタム・プールの各接続を調べて、それがOCIShardInstancesGet()で戻された名前を持ついずれかのインスタンスを指し示しているかどうかを確認します。カスタム・プールの接続が指し示しているインスタンスをチェックするには、サービス・コンテキスト・ハンドル(OCISvcCtx *)のOCI_ATTR_INSTNAMEを使用してインスタンス名を取得します。

  6. カスタム・プールに目的のインスタンスのいずれかを指し示す適切な接続が見つかったら、OCIAttrSet()をコールしてシャーディング・キーおよびスーパー・シャーディング・キーをその接続に関連付けます。これで、目的のシャードでアプリケーションのOCIコールを実行するための接続の準備が整いました。ステップ7はスキップできます。カスタム・プールに目的のインスタンスを指し示す適切な接続が見つからない場合は、ステップ7に進みます。

  7. 一致する接続が見つからない場合、シャーディング・キー、スーパー・シャーディング・キーおよび接続文字列を使用して新しい接続を作成し、OCISessionGet()をコールしてOCI_SESSGET_CUSTOM_POOLモードを指定することで、シャードとチャンクのマッピング情報が含まれるシャード・トポロジを明示的にキャッシュします。これにより、目的のシャードに対する接続が用意されました。これで、目的のシャードでアプリケーションのOCIコールを実行するための接続の準備が整いました。

シャーディング・キーまたはスーパー・シャーディング・キーをOCIに提供することで、目的のシャードに対する接続を取得できます。前述のとおり、目的のシャードに対する適切な接続を戻すことができるように、データベースに対するスタンドアロン接続を取得する前、またはOCIセッション・プールからの接続をチェックアウトする前に、これらのキーを指定する必要があります。

カスタム・プールの場合、プールが空であるときは、カスタム・プール実装者は、前述のステップを使用して、シャーディング・キーおよびスーパー・シャーディング・キーを(OCI_SESSGET_CUSTOM_POOLモードで)提供して目的のシャードに対するスタンドアロン接続を最初に作成し、カスタム・プールに移入できます。次に、特定のシャードへの接続に対する後続の要求について、OCI_ATTR_INSTNAMEのOCIAttrGet()と組み合せて説明のとおりOCIShardInstancesGet()コールを使用して、目的のシャードに対する既存の接続がカスタム・プールにすでに存在するかどうかを確認し、存在する場合はその接続を再利用できます。

この項では、次のようなOCIインタフェースについて説明します。

  • OCIデータ型を使用してシャーディング・キーおよびスーパー・シャーディング・キーを作成します。

  • シャーディング・キーおよびスーパー・シャーディング・キーを指定して接続を作成します。

  • OCIセッション・プールからの接続要求に対してシャーディング・キーまたはスーパー・シャーディング・キーを指定します。

  • カスタム接続プーリングを使用して、指定された接続に対応するシャード名を取得し、指定されたシャーディング・キーおよびスーパー・シャーディング・キーに対応するシャード名およびチャンク名を取得します。

スタンドアロン接続のシャーディング・キーおよびスーパー・シャーディング・キーの指定について

接続を作成するにはOCISessionGet()コールを使用します。このコールは、入力として認証ハンドルauthpを使用し、そこで特定のシャードに対する接続の作成をサポートする2つの属性(シャーディング・キーの場合はOCI_ATTR_SHARDING_KEY、スーパー・シャーディング・キーの場合はOCI_ATTR_SUPER_SHARDING_KEY)を含め、様々なプロパティを設定できます。

シャーディング・キーおよびスーパー・シャーディング・キーの作成について

シャーディング・キーおよびスーパー・シャーディング・キーを構成するには、OCI記述子型のOCIShardingKeyを使用します。この記述子は、キー値(単一のパート・キーの場合)または複数値(複合キーの場合)をラップします。

次のOCIShardingKeyColumnAdd()コールを使用して、完全なキーを構成するためにキーのすべての列を追加します。 
OCIShardingKeyColumnAdd(OCIShardingKey *shardingKey, 
                     OCIError    *errhp, 
                     void        *col, 
                     ub4          colLen, 
                     ub2          colType, 
                     ub4          mode)
データベースでキーが定義されている順序で、複合キーの列の数だけ(単純なシャーディング・キーの場合は1回のみ)このコールを実行する必要があります。columnTypeパラメータは、列のデータ型を示します。

次の表は、columnTypeパラメータでサポートされるOCIデータ型とその対応するCデータ型を示しています。

OCIデータ型 Cデータ型
SQLT_NUM ub1*
SQLT_CHR OraText*
SQLT_DATE ub1*
SQLT_TIMESTAMP OCIDateTime*
SQLT_RAW ub1*
SQLT_VNU ub1*
SQLY_INT int*

キャラクタ・キー値は、(NLS_LANGまたはOCIEnvNLSCreate()コールで指定された)クライアント文字セットであるとみなされます。

OCIShardingKeyColumnAdd()コールを使用してシャーディング・キーおよびスーパー・シャーディング・キーを構成した後、認証ハンドルでキーを設定するには、シャーディング・キー属性OCI_ATTR_SHARDING_KEYおよびスーパー・シャーディング・キー属性OCI_ATTR_SUPER_SHARDING_KEYを次のように使用します。 

OCIAttrSet(authp, 
           OCI_HTYPE_AUTHINFO, 
           shardKey, 
           sizeof(shardKey),
           OCI_ATTR_SHARDING_KEY,
           errhp);
OCIAttrSet(authp, 
           OCI_HTYPE_AUTHINFO, 
           shardGroupKey, 
           sizeof(shardGroupKey),
           OCI_ATTR_SUPER_SHARDING_KEY, 
           errhp);

OCISessionGet()コールでこのauthpパラメータを使用すると、設定されているシャーディング・キーおよびスーパー・シャーディング・キーの値に対応するデータを含むシャードに対する接続の作成が保証されます。

シャーディング・キーおよびスーパー・シャーディング・キーの実際の値の取得について

診断目的でシャーディング・キーおよびスーパー・シャーディング・キーのBASE64表現を確認する場合、OCIShardingKey記述子でOCI_ATTR_SHARDING_KEY_B64属性を使用できます。OCIAttrGet()コールは、入力としてOCIShardingKey記述子を使用して、シャーディング・キーおよびスーパー・シャーディング・キーのBASE64形式でテキスト値を戻します。 

OCIAttrGet((dvoid *) OCIShardingKey,
   (ub4)             OCI_DTYPE_SHARDING_KEY,
   (dvoid *)         &sekyVale, 
   (ub4*)            &skeyValueLen,
                     OCI_ATTR_SHARDING_KEY_B64, 
   (OCIError *)      errhp);

また、アプリケーションで次のようにOCIShardingKeyReset()コールを使用すると、新しいシャーディング・キーおよびスーパー・シャーディング・キーを作成するために、割当て済の記述子をリセットして再利用できます。 

sword OCIShardingKeyReset(OCIShardingKey *shardKey, 
                          OCIError       *errhp, 
                          ub4             mode);
この項には次のトピックが含まれます:

関連項目:

OCIセッション・プールから接続を取得するためのシャーディング・キーおよびスーパー・シャーディング・キーの指定について

OCIセッション・プールから接続を取得するためのシャーディング・キーおよびスーパー・シャーディング・キーの指定方法について説明します。

デフォルトでは、OCISessionGet()コールにより新しい接続を作成します。このコールを使用して、OCIセッション・プールから既存の接続を取得することもできます。OCI_ATTR_SHARDING_KEY属性とOCI_ATTR_SUPER_SHARDING_KEY属性の設定を使用すると、OCIセッション・プールから目的のシャードに対する接続を取得できます。OCIセッション・プールでは、プール内のセッションは、初期化済認証ハンドルのauthpを使用してOCISessionGet()コールから渡されるデータベース資格証明によってそれぞれ認証される様々なシャードを表します。

次の例は、指定された同種および文キャッシュ・モードで作成されたOCIセッション・プールから、目的のデータベース・シャードに対する接続を取得する方法を示しています。この例では同種プールを使用していますが、そのタイプのプールに限定されるわけではありません。

OCIShardingKey   *shardKey, *shardGroupKey;
  /* Error handling is omitted for brevity. */
  /* Create a homogeneous session pool. */
  checkerr(&status, errhp,
           OCISessionPoolCreate(envhp, errhp,
                 spoolhp,                                     /* session pool handle */
                (OraText **) poolName, poolNameLenp,          /* returned poolname, length */
                (const OraText *) connstr, strlen(connstr),   /* connect string */
                 min, max, increment,                         /* pool size constraints */
                (OraText *) "hr", strlen((char *) "hr"),      /* username */
                (OraText *) apppassword,                      /* password */
                 strlen((char *) apppassword),
                 OCI_SPC_HOMOGENEOUS|OCI_SPC_STMTCACHE));     /* modes */
                
/* Allocate the sharding key and super sharding key descriptors. */
OCIDescriptorAlloc(envhp,(dvoid **)&shardKey,
               OCI_DTYPE_SHARDING_KEY, 0,(dvoid **)0)))
text *name = “KK”;
text *gname = “GOLD”;
int  empid = 150;

/* Add all the columns of the key to form the final sharding key. */
OCIShardingKeyColumnAdd(shardKey,(ub1*)&empid, sizeof(empid), 
                               SQLT_INT, errhp, OCI_DEFAULT);
OCIShardingKeyColumnAdd(shardKey, name, strlen(name), 
                               SQLT_CHAR, errhp, OCI_DEFAULT));

OCIAttrSet(authp, OCI_HTYPE_AUTHINFO,
           shardKey, sizeof(shardKey),
           OCI_ATTR_SHARDING_KEY, errhp);

/* Setting a shard group key. */
/* Create a shard group key, in the same way as for a sharding key. */
OCIDescriptorAlloc(envhp,(dvoid **)&shardGroupKey,
                   OCI_DTYPE_SHARDING_KEY, 0, (dvoid **)0));

/* Add the column of the key to form the final super sharding key. */
OCIShardingKeyColumnAdd(shardGroupKey, gname, strlen(gname),
                     SQLT_CHAR, errhp, OCI_DEFAULT)); 

OCIAttrSet(authp, OCI_HTYPE_AUTHINFO,
           shardGroupKey, sizeof(shardGroupKey),
           OCI_ATTR_SUPER_SHARDING_KEY, errhp));

/* Get the database connection from the OCI Session Pool. */
checkerr(&status,
         errhp, OCISessionGet(envhp, errhp,
                &svchp,                              /* returned database connection */
                authp,                               /* initialized authentication handle */
               (OraText *) poolName, poolNameLen,    /* connect string */
                NULL, 0, NULL, NULL, NULL,           /* session tagging parameters: optional */ 
                OCI_DEFAULT));                       /* modes */

シャーディングでのチャンク移行およびOCISessionGet()

チャンク移行では、あるシャード・インスタンスから別のシャード・インスタンスへのチャンクの移行時に、OCIセッション・プールによって、OCISessionGet()がチャンク移行時に暗黙的に再試行を行うことで、書込み可能なチャンクを含むインスタンスに対する接続を戻すことが保証されます。この場合、次のいくつかのプロパティを設定する必要があります。

  • 接続文字列でREADONLY_CHUNK_OKをFALSEに設定します。

  • プール・ハンドル属性のOCI_ATTR_SPOOL_GETMODEおよびOCI_ATTR_SPOOL_WAIT_TIMEOUTを、OCI_SPOOL_ATTRVAL_TIMEDWAITと適切なタイムアウト値に設定します。タイムアウト期間内に書込み可能なインスタンスに対する接続をプールで取得できない場合、OCISessionGet()はORA-24495エラーを戻します。

アプリケーションで読取り専用チャンクを使用できる場合、接続文字列でREADONLY_CHUNK_OK=trueを設定できます。この場合、読取り専用とマークされたチャンクを含むインスタンスで使用できる接続も割り当てられます。このような接続でアプリケーションがデータベース書込み操作を試行すると、対応するエラーが発生します。

カスタム・プールから接続を取得するためのシャーディング・キーおよびスーパー・シャーディング・キーの指定について

カスタム・プールから接続を取得するためのシャーディング・キーおよびスーパー・シャーディング・キーの指定をサポートする機能について説明します。

この項では、カスタム・プールから接続を取得するためにシャーディング・キーおよびスーパー・シャーディング・キーを指定するアプリケーションをサポートする次の機能について説明します。

  • OCISessionGet()のモードOCI_SESSGET_CUSTOM_POOL - OCIが新しいシャード・インスタンスに接続するたびに明示的にシャード・トポロジをキャッシュするために使用します。

  • OCIShardInstancesGet() - 指定されたシャーディング・キー記述子、スーパー・シャーディング・キー記述子および接続文字列に対応するインスタンス名を戻します。

OCI_ATTR_INSTNAME属性

OCIクライアント・アプリケーションでカスタム接続プーリングを使用する場合、特定のシャードに対する接続を戻すことができる必要があります。これを行うには、接続が作成されているシャードのシャード名と、一致する接続の検索を可能にするシャーディング・キーおよびスーパー・シャーディング・キーとシャード名のマッピングを確認する必要があります。

これは、この目的でサービス・コンテキスト(svchp)のOCI_ATTR_INSTNAME属性を使用することで可能になります。この属性は、指定された接続に対応するインスタンス名を戻します。インスタンス名は、指定された接続によって指し示されたシャード・インスタンスにとって一意です。どのシャード・インスタンスにも一意の名前があります。次のコード例は、この属性を使用して、指定されたサービス・コンテキストsvchpからインスタンス名を取得する方法を示しています。 

OraText shardName[OCI_INSTNAME_MAXLEN];
ub4 shardNameLen;  
   OCIAttrGet(svchp,
   OCI_HTYPE_SVCCTX,
   shardName,
   (ub4 *) &shardNameLen,
   OCI_ATTR_INSTNAME,
   errhp);

OCISessionGet()のモードOCI_SESSGET_CUSTOM_POOL

カスタム・プーリングを実行するOCIクライアントは、OCISessionGet()のモードOCI_SESSGET_CUSTOM_POOLを使用して、OCIがまだアクセスしていない新しいシャードに接続するたびにシャードとチャンクのマッピング情報が含まれるシャード・トポロジを明示的にキャッシュする必要があります。カスタム・プーリングを使用しないOCIクライアントでは、このキャッシュはOCIセッション・プールの使用時などに暗黙的に実行されるため、このモードを使用する必要はありません。

OCIShardInstancesGet()

OCIShardInstancesGet()は、指定されたシャーディング・キー記述子およびスーパー・シャーディング・キー記述子に対応するインスタンス名を戻します。このメソッドのシグネチャは次のとおりです。 

sword OCIShardInstancesGet(
           void            **shTopoCtx,
           OCIError         *errhp,
           const OraText    *connstr,
           ub4               constrl,
           OCIShardingKey   *shardingKey,
           OCIShardingKey   *superShardingKey,
           OCIShardinst   ***shardinsts,
           ub4               numShardInsts,
           ub4               mode);

このコールは、クライアントのシャード・トポロジ・キャッシュを参照します。

OCI_SESSGET_CUSTOM_POOLモードで接続が作成されている場合、OCIは、シャード・トポロジ・キャッシュをローカルで管理します。

OCI_SESSGET_CUSTOM_POOLで接続が作成されていないため、またはOCI_SESSGET_CUSTOM_POOLでそれまでに作成された接続により要求されたシャーディング・キーおよびスーパー・シャーディング・キーのチャンクを含むシャードに接続していないため、シャード・トポロジ・キャッシュにまだマッピングが含まれない場合、戻される値はNULLになる可能性があります。どちらの場合でも、カスタム・プールは、OCI_SESSGET_CUSTOM_POOLモードを有効にして適切に設定されたOCI_ATTR_SHARDING_KEYおよびOCI_ATTR_SUPER_SHARDING_KEY属性に基づいて、OCISessionGet()を使用して新しい接続を明示的に作成する必要があります。これを行うと、OCIシャード・トポロジ・キャッシュに新しいシャードに関する情報が追加されます。後続のOCIShardInstancesGet()コールは、これらのシャードに存在するチャンクに属するキー範囲を検索し、これらのシャード・インスタンス名を戻します。

シャーディング・キーおよびスーパー・シャーディング・キーは、レプリケートされたチャンクの結果として複数のシャードを参照する可能性があることに注意してください。カスタム・プールに目的のシャードに対する接続が含まれる場合、カスタム・プールでは、割当ての前に接続でOCI_ATTR_SHARDING_KEYおよびOCI_ATTR_SUPER_SHARDING_KEYプロパティが設定されていることを確認する必要があります。これらのプロパティを設定することで、データベース側でチャンクの使用状況を追跡し、データベースでチャンクの分断が発生していないかどうかを確認できます。

関連項目:

カスタム・プーリングを使用する場合の例は、「OCIShardInstancesGet()」を参照してください

XStreamインタフェースの使用について

Oracle Database 11gリリース2より、Oracle Streamsで、高パフォーマンスな、Oracle DatabaseとOracle以外のデータベース、非RDBMS Oracle製品、ファイル・システム、サード・パーティ・ソフトウェア製品などと間のほぼリアルタイムの情報共有インフラストラクチャを実現する、eXtended Streams (XStream) OutとXStream Inと呼ばれる拡張APIが提供されるようになりました。

XStreamは、Streamsインフラストラクチャ上に構築されます。

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

関連項目:

OCI XStream関数

XStream Out

XStream Outは、リモート・クライアントのアウトバウンド・サーバーへの連結(Streams適用プロセス)、および論理変更レコード(LCR)形式での行変更の抽出を可能にします。

XStream Outを使用するには、他のStreams設定と同様、取得プロセスおよび適用プロセスを作成する必要があります。LOB、LONGおよびXMLTypeなど、Oracle Streamsでサポートされるすべてのデータ型がXStreamでサポートされます。そのような適用プロセスはアウトバウンド・サーバーと呼ばれます。取得およびアウトバウンド・サーバーは、同一のデータベース・インスタンス上にある場合とない場合があります。取得およびアウトバウンド・サーバーの開始後、行変更が取得され、アウトバウンド・サーバーに送信されます。外部クライアントは、OCIを使用してこのアウトバウンド・サーバーに接続できます。接続の確立後は、アウトバウンド・サーバーからのLCRの待機中、クライアントをループさせることができます。クライアントでは、クライアント側のコールバックがLCRが受信されるたびに起動されるように登録できます。必要に応じていつでもクライアントをアウトバウンド・サーバーから連結解除できます。再起動時には、アウトバウンド・サーバーはREDOストリームのどの位置でクライアントへのLCRのストリームを開始するか認識しています。

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

関連項目:

LCRストリーム

LCRストリームの特徴について説明します。

  • LCRストリームは反復可能である必要があります。

  • LCRストリームには、アセンブルおよびコミット済のトランザクションのリストが含まれている必要があります。

  • 1つのトランザクションからのLCRは連続しています。LCRストリーム内にはトランザクションのインターリーブはありません。

  • LCRストリーム内の各トランザクションには、LCRの順序付きリストとトランザクションIDが含まれている必要があります。

  • 各トランザクションの最後のLCRにはコミットLCRが含まれている必要があります。

  • 各LCRは固有の位置を持つ必要があります。

  • 1つのトランザクション内およびトランザクション間のすべてのLCRの位置は、確実に増加する必要があります。

処理済最低位置と再起動の考慮事項

アウトバウンド・サーバーまたはクライアントが異常終了した場合、この2つの間の接続は自動的に切断されます。再起動後に適切にリカバリされるようにするには、クライアントで処理済最低位置がメンテナンスされる必要があります。

処理済最低位置は、その位置以降、すべてのLCRがクライアントで処理されたことを示します。この位置は、各トランザクションの適用中にクライアント側でメンテナンスされる必要があります。クライアントでXStream Out APIが実行される間、この位置は定期的にサーバーに送信されます。この位置によって、その位置以降のすべてのLCRがクライアントで処理されたことがサーバーに示されるため、サーバーでは必要がなくなったREDOログを削除できます。

再起動するとすぐに、クライアントはアウトバウンド・サーバーに再度アタッチする必要があります。アタッチ・コールの間、クライアントは、受信した最後の位置をアウトバウンド・サーバーに通知できます。次に、アウトバウンド・サーバーは、この最後の位置より大きい位置を持つLCRを送信します。クライアントが最後の位置を指定しない場合(つまり、NULLを指定した場合)、アウトバウンド・サーバーはシステム表から処理済最低位置を取得し、開始位置を導出してREDOログを調べます。次に、この処理済最低位置より大きい位置を持つLCRをクライアントに送信します。

XStream In

非OracleデータをOracle Databaseにレプリケートするには、XStream Inを使用します。これにより、リモート・クライアントのインバウンド・サーバーへの連結(Streams適用プロセセス)、およびLCR形式での行およびDDL変更の送信が可能になります。

外部クライアント・アプリケーションは、OCIを使用してこのインバウンド・サーバーに接続されます。接続の確立後、クライアント・アプリケーションは、LCRをストリームすることによりインバウンド・サーバーの取得エージェントとして機能します。クライアント・アプリケーションは、データベース接続ごとに1つのインバウンド・サーバーにのみ連結できます。各インバウンド・サーバーには1つのクライアントのみを連結できます。

XStream Inでは、Oracle Streamsの次の機能が使用されます。

  • 適用プロセスおよびオプションの適用プロセスの並列を使用した、DML変更の高パフォーマンス処理。

  • SQL生成、競合検出と解決、エラー処理および適用ハンドラを使用した処理のカスタマイズなどの適用プロセス機能。

  • ラウンド・トリップが最小限である情報のネットワーク伝達ストリーム。

XStream Inでは、LOB、LONG、LONG RAWおよびXMLTypeなど、Oracle Streamsでサポートされているすべてのデータ型がサポートされています。クライアント・アプリケーションから、LOBおよびXMLTypeデータがチャンクでインバウンド・サーバーに送信されます。複数のチャンクで単一のLOBまたはXMLTypeの列値が構成されます。

この項には次のトピックが含まれます:
処理済最低位置と再起動機能

処理済最低位置は、その位置以降、インバウンド・サーバーでLCRが必要とされないことを示します。

この位置は、取得プロセスで取得された変更を適用するOracle Streams適用プロセスの最も古いSCNに対応します。

処理済最低位置は、この位置以下のLCRがインバウンド・サーバーで処理済であることを示します。クライアントがインバウンド・サーバーに再連結される場合、インバウンド・サーバーでこの処理済最低位置以下のすべてのLCRは破棄されるため、この処理済最低位置より上のLCRのみがそれから送信される必要があります。

クライアント・アプリケーションが異常終了した場合は、クライアント・アプリケーションとインバウンド・サーバー間の接続は自動的に切断されます。再起動時、クライアント・アプリケーションで処理済最低位置がインバウンド・サーバーから取り出され、この処理済最低位置から変更を取り出すように取得エージェントに指示が出されます。

XStream Inインタフェースを使用してクライアント・アプリケーションのリカバリ時間を制限するため、クライアント・アプリケーションから空のトランザクションなどのアクティビティを定期的にインバウンド・サーバーに送信できます。サーバーに送信するLCRが存在しない場合、インバウンド・サーバーの処理済最低位置に進むように、コミット・ディレクティブとともに行LCRをクライアントから送信できます。このアクティビティは、インバウンド・サーバーの処理済最低位置を進めることができるという承認の役割を果たします。インバウンド・サーバーに送信されるLCRストリームは、前述のXStream OutのLCRストリーム・プロパティに従う必要があります。

ストリーム位置

ストリーム位置は、指定したLCRストリーム内のLCRの位置を示します。

Oracle Database外で取得されたトランザクションの場合、ストリーム位置はバイト比較をサポートしている特定の形式(ベース16エンコードなど)でエンコードされる必要があります。ストリーム位置は、XStream Inインタフェースを使用してクライアントから送信されるトランザクション・ストリームの全順序へのキーです。

XStreamsのセキュリティ

XStreamsのセキュリティ特性について説明します。

XStream Outでは、システム・レベルの権限を必要とせずに、通常のユーザーによるLCRの取り出しが可能です。DBAロールなどのシステム・レベルの権限は、XStream Outの構成に必要です。XStream Outを構成するユーザーは、LCRを取得するためのアウトバウンド・サーバーへの連結が可能な接続ユーザーとして通常のユーザーを指定できます。

XStream Inでは、通常ユーザーはXStream Inの構成に必要なシステム・レベルの特権(DBAなど)を必要とせずに、独自のスキーマで表を更新できます。

XStreamでは、インバウンドまたはアウトバウンド・サーバーに接続されたユーザーが信頼できるか想定できません。

OCIクライアントは、データベースで作成されたXStreamアウトバウンドまたはインバウンド・サーバーにアタッチする前に、Oracle Databaseに接続する必要があります。接続済のユーザーは、アタッチしたアウトバウンド・サーバーで構成されたconnect_userまたはアタッチしたインバウンド・サーバーで構成されたapply_userと同じである必要があります。同じでない場合は、エラーが発生します。

関連項目:

Oracle XStreamsの構成の詳細は、Oracle Database XStreamガイドを参照してください


脚注の凡例

脚注1:

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