19 DBMS_APPLICATION_INFO

アプリケーション開発者は、Oracle TraceおよびSQLトレース機能を持つDBMS_APPLICATION_INFOパッケージを使用して、実行しているモジュール名またはトランザクションをデータベースに記録できます。この記録は、後で行う様々なモジュールおよびデバッグのパフォーマンスを追跡するときに使用されます。

この章のトピックは、次のとおりです:

19.1 DBMS_APPLICATION_INFOの概要

アプリケーションを登録することによって、システム管理者およびパフォーマンス・チューニング担当者は、パフォーマンスをモジュール別に追跡できます。システム管理者は、モジュール別のリソース使用率をこの情報から追跡することもできます。アプリケーションをデータベースに登録すると、その名前およびアクションがV$SESSIONおよびV$SQLAREAビューに記録されます。

19.2 DBMS_APPLICATION_INFOのセキュリティ・モデル

これ以上の権限は不要です。DBMSAPIN.SQLスクリプトは、標準データベース作成の一部としてすでに実行されています。

注意:

DBMS_APPLICATION_INFOのパブリック・シノニムが作成前に削除されることはありません。これは、ユーザーがパブリック・シノニムをユーザー独自のパッケージまでリダイレクトできるようにするためです。

19.3 DBMS_APPLICATION_INFOの使用上の注意

ユーザーがモジュールを入力するたびに、アプリケーションがモジュール名およびアクション名を自動的に設定するようにしてください。モジュール名は、Oracle Formsアプリケーションのフォーム名またはOracleプリコンパイラ・アプリケーションのコード・セグメント名である場合があります。アクション名は、通常、モジュール内の現行トランザクションの名前または説明にしてください。

モジュールに基づいて独自の統計情報を収集する場合は、統計を最初に収集する別のスキーマにこのパッケージのバージョンを記述してこのパッケージにラッパーを実装してから、SYSバージョンのパッケージをコールします。このようにして、DBMS_APPLICATION_INFOのパブリック・シノニムを、DBAバージョンのパッケージまで変更できます。

19.4 DBMS_APPLICATION_INFOサブプログラムの要約

この表は、DBMS_APPLICATION_INFOパッケージのサブプログラムについて説明しています。

表19-1 DBMS_APPLICATION_INFOパッケージのサブプログラム

サブプログラム 説明

READ_CLIENT_INFOプロシージャ

現行セッションのclient_infoフィールドの値を読み込みます。

READ_MODULEプロシージャ

現行セッションのモジュールおよびアクションのフィールド値を読み込みます。

SET_ACTIONプロシージャ

現行モジュール内の現行アクション名を設定します。

SET_CLIENT_INFOプロシージャ

セッションのclient_infoフィールドを設定します。

SET_MODULEプロシージャ

現在実行中のモジュール名を新規モジュールに設定します。

SET_SESSION_LONGOPSプロシージャ

V$SESSION_LONGOPS表に行を設定します。

19.4.1 READ_CLIENT_INFOプロシージャ

このプロシージャは、現行セッションのclient_infoフィールドの値を読み込みます。

構文

DBMS_APPLICATION_INFO.READ_CLIENT_INFO (
   client_info OUT VARCHAR2); 

パラメータ

表19-2 READ_CLIENT_INFOプロシージャのパラメータ

パラメータ 説明

client_info

SET_CLIENT_INFOプロシージャに提供された最新のクライアント情報の値

19.4.2 READ_MODULEプロシージャ

このプロシージャは、現行セッションのモジュールおよびアクション・フィールドの値を読み込みます。

構文

DBMS_APPLICATION_INFO.READ_MODULE ( 
   module_name OUT VARCHAR2, 
   action_name OUT VARCHAR2); 

パラメータ

表19-3 READ_MODULEプロシージャのパラメータ

パラメータ 説明

module_name

SET_MODULEのコールによってモジュール名に設定された最後の値

action_name

SET_ACTIONまたはSET_MODULEのコールによってアクション名に設定された最後の値

使用上の注意

登録アプリケーションのモジュール名およびアクション名は、V$SQLAREAを問い合せるか、またはREAD_MODULEプロシージャをコールして取り出せます。クライアント情報は、V$SESSIONビューを問い合せるか、またはREAD_CLIENT_INFOプロシージャをコールして取り出せます。

次の問合せのサンプルは、V$SQLAREAMODULEおよびACTION列の使用方法の例です。

SELECT sql_text, disk_reads, module, action 
FROM v$sqlarea 
WHERE module = 'add_employee'; 

SQL_TEXT DISK_READS MODULE ACTION 
------------------- ---------- ------------------ ---------------- 
INSERT INTO emp 1 add_employee insert into emp 
(ename, empno, sal, mgr, job, hiredate, comm, deptno) 
VALUES 
(name, next.emp_seq, manager, title, SYSDATE, commission, department) 

1 row selected.

19.4.3 SET_ACTIONプロシージャ

このプロシージャは、現行モジュール内の現行アクション名を設定します。

構文

DBMS_APPLICATION_INFO.SET_ACTION (
   action_name IN VARCHAR2); 

パラメータ

表19-4 SET_ACTIONプロシージャのパラメータ

パラメータ 説明

action_name

現行モジュール内の現行アクション名。現行アクションが終了したときは、次のアクションがある場合はその名前で、ない場合はNULLでこのプロシージャをコールします。32バイトを超える名前は切り捨てられます。

使用上の注意

アクション名には、実行されている現行のアクションを説明する名前を設定してください。アクション名は、すべてのトランザクションの開始前に設定することをお薦めします。

後続のトランザクションのログが正しく記録されるように、トランザクション完了後はトランザクション名をNULLに設定してください。トランザクション名をNULLに設定しないと、後続のトランザクションのログがその前のトランザクション名で記録される可能性があります。

次のコードは、登録プロシージャを使用するトランザクションの例です。

CREATE OR REPLACE PROCEDURE bal_tran (amt IN NUMBER(7,2)) AS 
BEGIN 

-- balance transfer transaction 

   DBMS_APPLICATION_INFO.SET_ACTION(
      action_name => 'transfer from chk to sav'); 
   UPDATE chk SET bal = bal + :amt 
      WHERE acct# = :acct; 
   UPDATE sav SET bal = bal - :amt 
      WHERE acct# = :acct; 
   COMMIT; 
   DBMS_APPLICATION_INFO.SET_ACTION(null); 

END;  

19.4.4 SET_CLIENT_INFOプロシージャ

このプロシージャは、クライアント・アプリケーションに関する追加情報を提供します。

構文

DBMS_APPLICATION_INFO.SET_CLIENT_INFO (
   client_info IN VARCHAR2); 

パラメータ

表19-5 SET_CLIENT_INFOプロシージャのパラメータ

パラメータ 説明

client_info

クライアント・アプリケーションに関するあらゆる追加情報を提供します。この情報は、V$SESSIONビューに格納されています。64バイトを超える情報は切り捨てられます。

注意:

CLIENT_INFOは、ユーザーによる読込みおよび書込みが可能です。保護アプリケーション属性の格納には、アプリケーション・コンテキスト機能を使用できます。

19.4.5 SET_MODULEプロシージャ

このプロシージャは、現行のアプリケーションまたはモジュールの名前を設定します。

構文

DBMS_APPLICATION_INFO.SET_MODULE ( 
   module_name IN VARCHAR2, 
   action_name IN VARCHAR2); 

パラメータ

表19-6 SET_MODULEプロシージャのパラメータ

パラメータ 説明

module_name

現在実行中のモジュール名。現行のモジュールが終了したときは、新規モジュールがある場合はその名前で、ない場合はNULLでこのプロシージャをコールします。48バイトを超える名前は切り捨てられます。

action_name

現行モジュール内の現行アクション名。アクションを指定しない場合は、この値をNULLに設定してください。32バイトを超える名前は切り捨てられます。

使用上の注意

CREATE or replace PROCEDURE add_employee( 
  name VARCHAR2, 
  salary NUMBER, 
  manager NUMBER, 
  title VARCHAR2, 
  commission NUMBER, 
  department NUMBER) AS 
BEGIN 
  DBMS_APPLICATION_INFO.SET_MODULE( 
    module_name => 'add_employee', 
    action_name => 'insert into emp'); 
  INSERT INTO emp 
    (ename, empno, sal, mgr, job, hiredate, comm, deptno) 
    VALUES (name, emp_seq.nextval, salary, manager, title, SYSDATE, 
            commission, department); 
  DBMS_APPLICATION_INFO.SET_MODULE(null,null); 
END;

19.4.6 SET_SESSION_LONGOPSプロシージャ

このプロシージャは、V$SESSION_LONGOPSビューに行を設定します。このビューは、長時間にわたって実行する操作の進行状況を示すために使用されます。パラレル実行やServer Managed Recoveryなどの一部のOracle機能は、このビューの行を使用してデータベース・バックアップなどの状態を示します。

アプリケーション固有の長時間実行タスクの進行状況に関する情報を通知するために、アプリケーションでSET_SESSION_LONGOPSプロシージャを使用できます。この結果、V$SESSION_LONGOPSビューで進行状況を監視できます。

構文

DBMS_APPLICATION_INFO.SET_SESSION_LONGOPS (
   rindex      IN OUT BINARY_INTEGER,
   slno        IN OUT BINARY_INTEGER,
   op_name     IN     VARCHAR2       DEFAULT NULL,
   target      IN     BINARY_INTEGER DEFAULT 0,
   context     IN     BINARY_INTEGER DEFAULT 0,
   sofar       IN     NUMBER         DEFAULT 0,
   totalwork   IN     NUMBER         DEFAULT 0,
   target_desc IN     VARCHAR2       DEFAULT 'unknown target',
   units       IN     VARCHAR2       DEFAULT NULL)  

set_session_longops_nohint constant BINARY_INTEGER := -1;

パラメータ

表19-7 SET_SESSION_LONGOPSプロシージャのパラメータ

パラメータ 説明

rindex

更新するv$session_longops行を示すトークン。新規行を使用するには、このトークンをset_session_longops_nohintに設定します。行を再利用する場合は、先行するコールの戻り値を使用します。

slno

set_session_longopsへのコール全体の情報を保存しますが、内部使用のためのパラメータであるため、コール元で修正しないでください。

op_name

長時間実行タスクの名前を指定します。v$session_longopsOPNAME列に表示されます。最大長は64バイトです。

target

長時間実行操作中に処理されるオブジェクトを指定します。たとえば、ソートされる表のIDなどを指定します。v$session_longopsTARGET列に表示されます。

context

クライアントが格納する数。v$session_longopsCONTEXT列に表示されます。

sofar

クライアントが格納する数。v$session_longopsSOFAR列に表示されます。これは通常、その時点までに処理した作業量です。

totalwork

クライアントが格納する数。v$session_longopsTOTALWORK列に表示されます。これは通常、この長時間実行操作で行う必要がある推定合計作業量です。

target_desc

この長時間操作で操作されるオブジェクトの説明を指定します。この結果、targetパラメータにキャプションが提供されます。この値は、v$session_longopsTARGET_DESCフィールドに表示されます。最大長は32バイトです。

units

sofarおよびtotalworkを表す単位を指定します。v$session_longopsUNITSフィールドに表示されます。最大長は32バイトです。

この例では、ループ内で10個のオブジェクトに対してタスクを実行します。各オブジェクトの処理が完了するたびに、プロシージャの進行状況に関するV$SESSION_LONGOPSが更新されます。

DECLARE
        rindex    BINARY_INTEGER;
        slno      BINARY_INTEGER;
        totalwork number;
        sofar     number;
        obj       BINARY_INTEGER;
 
      BEGIN
        rindex := dbms_application_info.set_session_longops_nohint;
        sofar := 0;
        totalwork := 10;
 
        WHILE sofar < 10 LOOP
          -- update obj based on sofar
          -- perform task on object target
 
          sofar := sofar + 1;
          dbms_application_info.set_session_longops(rindex, slno,
            "Operation X", obj, 0, sofar, totalwork, "table", "tables");
        END LOOP;
      END;