ヘッダーをスキップ
Oracle Database PL/SQLパッケージ・プロシージャおよびタイプ・リファレンス
11g リリース1（11.1）
E05686-02
  目次
目次		 索引
索引
戻る
戻る 		 次へ
次へ		  

86 DBMS_OUTPUT

DBMS_OUTPUTパッケージによって、ストアド・プロシージャ、パッケージおよびトリガーからメッセージを送信できます。このパッケージは、PL/SQLデバッグ情報の表示に特に便利です。

この章では、次の項目について説明します。

DBMS_OUTPUTの使用方法

この項では、DBMS_OUTPUTパッケージの使用に関連する項目について説明します。

概要

通常、このパッケージは、デバッグに使用されるか、あるいはメッセージとレポート（プロシージャにSQLコマンドDESCRIBEを適用するなどして生成）をSQL*DBAまたはSQL*Plusに表示するために使用されます。

このパッケージに含まれているPUTプロシージャおよびPUT_LINEプロシージャによって、別のトリガー、プロシージャまたはパッケージで読み込めるバッファに情報を設定できます。 別のPL/SQLプロシージャまたは無名ブロックでは、GET_LINEプロシージャおよびGET_LINESプロシージャをコールして、バッファに入れた情報を表示できます。

パッケージを無効にすると、サブプログラムに対するすべてのコールが無視されます。これによって、クライアントが情報を処理できる場合のみにサブプログラムが使用可能になるように、アプリケーションを設計できます。

セキュリティ・モデル

dbmsotpt.sqlスクリプトは、ユーザーSYSとして実行する必要があります。 これによって、パブリック・シノニムDBMS_OUTPUTが作成され、このパッケージに対するEXECUTE許可がpublicに付与されます。

使用上の注意


注意:

DBMS_OUTPUTを使用して送信するメッセージは、送信サブプログラムまたはトリガーが完了するまでは実際に送信されません。プロシージャの実行中に出力をフラッシュするメカニズムはありません。

例外

DBMS_OUTPUTサブプログラムでアプリケーション・エラーORA-20000が発生すると、出力プロシージャは次のエラーを戻すことができます。

表86-1 DBMS_OUTPUTエラー

エラー 説明

ORU-10027:

バッファのオーバーフロー。

ORU-10028:

行の長さのオーバーフロー。

ルールおよび制限

例

例1: トリガーを使用した出力

トリガーを使用して、デバッグ処理の結果を出力できます。たとえば、次のコマンドを実行するトリガーをコード化できます。

DBMS_OUTPUT.PUT_LINE('I got here:'||:new.col||' is the new value');

DBMS_OUTPUTパッケージを使用可能にした場合、このPUT_LINEによって生成されたテキストはバッファに入れられ、トリガー文（トリガーを起動させるINSERT、DELETEまたはUPDATEが想定できます）の実行後に、情報行を取り出すことができます。次に例を示します。

BEGIN
   DBMS_OUTPUT.GET_LINE(:buffer, :status);
END;

これによって、スクリーンにバッファを表示できます（オプション）。 statusが0（ゼロ）以外で戻るまで、GET_LINEへのコールを繰り返します。 パフォーマンス向上のためには、行の配列を戻すことができるGET_LINESプロシージャへのコールを使用してください。

例2: ストアド・プロシージャとトリガーのデバッグ

DBMS_OUTPUTパッケージは、一般的に、ストアド・プロシージャおよびトリガーをデバッグするために使用されます。また、「例3: オブジェクトに関する情報の取得」で示すように、このパッケージを使用すると、オブジェクトの情報を取り出し、その出力をフォーマットできます。

このファンクションは、従業員表を問い合せて、指定部門の給与合計を戻します。 このファンクションには、次のようにPUT_LINEプロシージャへのコールがいくつか含まれます。

CREATE FUNCTION dept_salary (dnum NUMBER) RETURN NUMBER IS
   CURSOR emp_cursor IS
      SELECT sal, comm FROM emp WHERE deptno = dnum;
   total_wages    NUMBER(11, 2) := 0;
   counter        NUMBER(10) := 1;
BEGIN

   FOR emp_record IN emp_cursor LOOP
      emp_record.comm := NVL(emp_record.comm, 0);
      total_wages := total_wages + emp_record.sal
         + emp_record.comm;
      DBMS_OUTPUT.PUT_LINE('Loop number = ' || counter ||
         '; Wages = '|| TO_CHAR(total_wages));  /* Debug line */
      counter := counter + 1; /* Increment debug counter */
   END LOOP;
   /* Debug line */
   DBMS_OUTPUT.PUT_LINE('Total wages = ' ||
     TO_CHAR(total_wages));
   RETURN total_wages;

END dept_salary;

EMP表には、次の行が含まれているとします。

EMPNO          SAL     COMM     DEPT
-----        ------- -------- -------
1002           1500      500      20
1203           1000               30
1289           1000               10
1347           1000      250      20

ユーザーがSQL*Plusの次の文を実行したとします。

SET SERVEROUTPUT ON
VARIABLE salary NUMBER;
EXECUTE :salary := dept_salary(20);

出力ペインには、次の情報が表示されます。

Loop number = 1; Wages = 2000
Loop number = 2; Wages = 3250
Total wages = 3250

PL/SQL procedure successfully executed.

例3: オブジェクトに関する情報の取得

この例では、ユーザーはすでにEXPLAIN PLANコマンドを使用して、ある文の実行計画に関する情報を取り出し、その情報をPLAN_TABLEに格納してあります。また、ユーザーはこの文に文IDを割り当ててあります。 EXPLAIN_OUTプロシージャの例では、表から情報を取り出し、出力をネスト形式でフォーマットして、SQL文を処理するステップの順序を厳密に記述しています。

 /****************************************************************/
/* Create EXPLAIN_OUT procedure. User must pass STATEMENT_ID to */
/* to procedure, to uniquely identify statement.                */
/****************************************************************/
CREATE OR REPLACE PROCEDURE explain_out
   (statement_id IN VARCHAR2) AS

   -- Retrieve information from PLAN_TABLE into cursor EXPLAIN_ROWS.

   CURSOR explain_rows IS
      SELECT level, id, position, operation, options,
         object_name
      FROM plan_table
      WHERE statement_id = explain_out.statement_id
      CONNECT BY PRIOR id = parent_id
         AND statement_id = explain_out.statement_id
      START WITH id = 0
       ORDER BY id;

BEGIN

   -- Loop through information retrieved from PLAN_TABLE:

   FOR line IN explain_rows LOOP

      -- At start of output, include heading with estimated cost.

      IF line.id = 0 THEN
         DBMS_OUTPUT.PUT_LINE ('Plan for statement '
            || statement_id
            || ', estimated cost = ' || line.position);
      END IF;

      -- Output formatted information. LEVEL determines indention level.

      DBMS_OUTPUT.PUT_LINE (lpad(' ',2*(line.level-1)) ||
         line.operation || ' ' || line.options || ' ' ||
         line.object_name);
   END LOOP;

END;

関連項目:

第206章「UTL_FILE」

データ構造

DBMS_OUTPUTパッケージは、GET_LINESプロシージャで使用するために、2つのコレクション・タイプを宣言します。

表タイプ

CHARARR表タイプ

オブジェクト・タイプ

DBMSOUTPUT_LINESARRAYオブジェクト・タイプ

CHARARR表タイプ

このパッケージ・タイプは、PUTプロシージャおよびPUT_LINEプロシージャを介して送信されたテキストを取得するために、GET_LINESプロシージャで使用されます。

構文

TYPE CHARARR IS TABLE OF VARCHAR2(32767) INDEX BY BINARY_INTEGER;

DBMSOUTPUT_LINESARRAYオブジェクト・タイプ

このパッケージ・タイプは、PUTプロシージャおよびPUT_LINEプロシージャを介して送信されたテキストを取得するために、GET_LINESプロシージャで使用されます。

構文

TYPE DBMSOUTPUT_LINESARRAY IS
     VARRAY(2147483647) OF VARCHAR2(32767);

DBMS_OUTPUTサブプログラムの要約

表86-2 DBMS_OUTPUTパッケージのサブプログラム

サブプログラム 説明

DISABLEプロシージャ

メッセージの出力を使用禁止にします。

ENABLEプロシージャ

メッセージの出力を使用可能にします。

GET_LINEプロシージャ

バッファから1行取り出します。

GET_LINESプロシージャ

バッファから行の配列を1つ取り出します。

NEW_LINEプロシージャ

PUTを使用して作成した行を終了します。

PUTプロシージャ

行をバッファに設定します。

PUT_LINEプロシージャ

行の一部をバッファに設定します。


注意:

NUMBERデータ型を使用するPUTプロシージャは使用されなくなります。現在はサポートされていますが、このリリースに含まれているのは下位互換性を保つという理由にすぎません。

DISABLEプロシージャ

このプロシージャは、PUT、PUT_LINE、NEW_LINE、GET_LINEおよびGET_LINESへのコールを使用禁止にして、残っている情報のバッファをパージします。

ENABLEプロシージャと同様に、SQL*PlusのSERVEROUTPUTオプションを使用する場合は、このプロシージャをコールする必要はありません。

構文

DBMS_OUTPUT.DISABLE;

プラグマ

pragma restrict_references(disable,WNDS,RNDS);

ENABLEプロシージャ

このプロシージャは、PUT、PUT_LINE、NEW_LINE、GET_LINEおよびGET_LINESへのコールを使用可能にします。 DBMS_OUTPUTパッケージがアクティブ化されていない場合、これらのプロシージャへのコールは無視されます。

構文

DBMS_OUTPUT.ENABLE (
   buffer_size IN INTEGER DEFAULT 20000);

プラグマ

pragma restrict_references(enable,WNDS,RNDS);

パラメータ

表86-3 ENABLEプロシージャのパラメータ

パラメータ 説明

buffer_size

バッファに入れられる情報量の上限（バイト）。 buffer_sizeをNULLに設定すると、制限なしと指定されます。

使用上の注意

GET_LINEプロシージャ

このプロシージャは、バッファに入れられた単一行の情報を取り出します。

構文

DBMS_OUTPUT.GET_LINE (
   line    OUT VARCHAR2,
   status  OUT INTEGER);

パラメータ

表86-4 GET_LINEプロシージャのパラメータ

パラメータ 説明

line

最後の改行文字を除いて、バッファに入れられた単一行の情報を戻します。「ORA-06502: PL/SQL: 数値または値のエラーが発生しました: 文字列バッファが小さすぎます。」の発生を回避するために、このパラメータの実際の値をVARCHAR2 (32767)として宣言する必要があります。

status

コールが正常に完了すると、ステータス0（ゼロ）が戻ります。バッファにこれ以上行がない場合は、ステータス1が戻ります。

使用上の注意

GET_LINESプロシージャ

このプロシージャは、バッファから行の配列を取り出します。

構文

DBMS_OUTPUT.GET_LINES (
   lines       OUT     CHARARR,
   numlines    IN OUT  INTEGER);

DBMS_OUTPUT.GET_LINES (
   lines       OUT     DBMSOUTPUT_LINESARRAY,
   numlines    IN OUT INTEGER);

パラメータ

表86-5 GET_LINESプロシージャのパラメータ

パラメータ 説明

lines

バッファに入れられた情報の行の配列を戻します。配列の各行の最大長は32767バイトです。PL/SQL無名ブロックからプロシージャを実行するには、3GLホスト・プログラムのVARRAYオーバーロード・バージョンを使用することをお薦めします。

numlines

バッファから取り出す行数。

プロシージャは、指定の行数を取り出した後、実際に取り出した行数を戻します。この数が要求した行数より少ない場合は、バッファにそれ以上行がない場合です。

使用上の注意

NEW_LINEプロシージャ

このプロシージャは、行端マーカーを設定します。 GET_LINEプロシージャおよびGET_LINESプロシージャは、改行で区切られた行を戻します。 PUT_LINEプロシージャまたはNEW_LINEプロシージャへのすべてのコールによって、GET_LINE（S）で戻される行が生成されます。

構文

DBMS_OUTPUT.NEW_LINE;

PUTプロシージャ

このプロシージャは、行の一部をバッファに設定します。


注意:

NUMBERデータ型を使用するPUTプロシージャは使用されなくなります。現在はサポートされますが、このリリースに含まれているのは下位互換性を保つという理由にすぎません。

構文

DBMS_OUTPUT.PUT (
    item IN VARCHAR2);

パラメータ

表86-6 PUTプロシージャのパラメータ

パラメータ 説明

item

バッファに設定する項目。

例外

表86-7 PUTプロシージャの例外

エラー 説明

ORA-20000、ORU-10027:

バッファのオーバーフロー。バッファは<buf_limit>バイトに制限されています。

ORA-20000、ORU-10028:

行の長さのオーバーフロー。各行につき32767バイトに制限されています。

使用上の注意

PUT_LINEプロシージャ

このプロシージャは、行をバッファに設定します。


注意:

NUMBERデータ型を使用するPUT_LINEプロシージャは使用されなくなります。現在はサポートされますが、このリリースに含まれているのは下位互換性を保つという理由にすぎません。

構文

DBMS_OUTPUT.PUT_LINE (
   item IN VARCHAR2);

パラメータ

表86-8 PUT_LINEプロシージャのパラメータ

パラメータ 説明

item

バッファに設定する項目。

例外

表86-9 PUT_LINEプロシージャの例外

エラー 説明

ORA-20000、ORU-10027:

バッファのオーバーフロー。バッファは<buf_limit>バイトに制限されています。

ORA-20000、ORU-10028:

行の長さのオーバーフロー。各行につき32767バイトに制限されています。

使用上の注意

  戻る
戻る 		 次へ
次へ
  目次
目次		 索引
索引