DBMS_OUTPUT

4 DBMS_OUTPUT

DBMS_OUTPUTパッケージを使用すると、ストアド・プロシージャおよびパッケージからメッセージを送信できます。このパッケージは、PL/SQLデバッグ情報を表示する場合に特に役立ちます。

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

DBMS_OUTPUTの使用
- 概要
- 操作上のノート
- ルールおよび制限
- 例外
- 例
データ構造
- 表タイプ
DBMS_OUTPUTサブプログラム

DBMS_OUTPUTの使用

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

概要

このパッケージのPUTプロシージャおよびPUT_LINEプロシージャを使用すると、別のプロシージャまたはパッケージが読み取ることができるバッファに情報を格納できます。GET_LINEプロシージャおよびGET_LINESプロシージャをコールすると、バッファされた情報を個別のPL/SQLプロシージャまたは無名ブロックで表示できます。

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

操作上のノート

GET_LINEをコールしない場合、またはttIsqlの画面にメッセージを表示しない場合、バッファに入れたメッセージは無視されます。
ttIsqlユーティリティは、SQL文または無名PL/SQLコールを発行した後、GET_LINESをコールします。
ttIsqlでSET SERVEROUTPUT ONを入力すると、次と同じ効果があります。
```
DBMS_OUTPUT.ENABLE (buffer_size => NULL);
```
出力に制限はありません。
一般に、アプリケーション・コードでDISABLEプロシージャまたはENABLEプロシージャを起動させると、出力を表示するかどうかを制御するttIsqlなどの外部ツールの試行を妨害する可能性があるため、アプリケーション・コードでは起動させないでください。

ノート:

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

ルールおよび制限

行の最大サイズは32767バイトです。
デフォルトのバッファ・サイズは20000バイトです。最小サイズは2000バイトですが、最大サイズに制限はありません。

例外

DBMS_OUTPUTサブプログラムによって、アプリケーション・エラーORA-20000が発生し、出力プロシージャから次のエラーが戻されることがあります。

表4-1 DBMS_OUTPUT例外

例外	説明
`ORU-10027`	バッファのオーバーフロー
`ORU-10028`	行の長さのオーバーフロー

例

通常、DBMS_OUTPUTパッケージは、ストアド・プロシージャまたはファンクションのデバッグに使用されます。

このファンクションは、HRスキーマのemployees表を問い合わせ、指定した部門の合計給与を戻します。ファンクションには、PUT_LINEプロシージャへのコールが含まれています。

CREATE OR REPLACE FUNCTION dept_salary (dnum NUMBER) RETURN NUMBER IS
   CURSOR emp_cursor IS
   select salary, commission_pct from employees where department_id = dnum;
   total_wages NUMBER(11, 2) := 0;
   counter NUMBER(10) := 1;
BEGIN
   FOR emp_record IN emp_cursor LOOP
       emp_record.commission_pct := NVL(emp_record.commission_pct, 0);
       total_wages := total_wages + emp_record.salary
                   + emp_record.commission_pct;
       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;

ユーザーがttIsqlで次の文を実行するとします。

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

次のような出力が表示されます。

Loop number = 1; Wages = 13000
Loop number = 2; Wages = 19000
Total wages = 19000 

PL/SQL procedure successfully executed.

データ構造

DBMS_OUTPUTパッケージでは、GET_LINESプロシージャで使用するために、2つの表タイプが宣言されます。

ノート:

PLS_INTEGERデータ・タイプとBINARY_INTEGERデータ・タイプは同じです。このドキュメントでは、リファレンス情報でデータ・タイプ(表タイプ、レコード・タイプ、サブプログラム・パラメータ、サブプログラム戻り値など)を示す場合にBINARY_INTEGERを使用しますが、説明および例ではいずれも使用される場合があります。
INTEGERデータ・タイプとNUMBER(38)データ・タイプも同じです。このドキュメントでは、全体をとおしてINTEGERを使用します。

表タイプ

CHARARR表タイプ

DBMSOUTPUT_LINESARRAY表タイプ

CHARARR表タイプ

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

構文

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

DBMSOUTPUT_LINESARRAY表タイプ

構文

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

DBMS_OUTPUTサブプログラム

表4-2に、DBMS_OUTPUTのサブプログラムの概要と各サブプログラムの詳細な説明を示します。

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

サブプログラム	説明
DISABLEプロシージャ	メッセージの出力を無効にします。
ENABLEプロシージャ	メッセージの出力を有効にします。
GET_LINEプロシージャ	バッファから1行を取り出します。
GET_LINESプロシージャ	バッファから行の配列を取り出します。
NEW_LINEプロシージャ	`PUT`で作成された行を終了します。
PUTプロシージャ	行の一部をバッファに格納します。
PUT_LINEプロシージャ	バッファに1行を格納します。

DISABLEプロシージャ

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

ENABLEプロシージャと同様に、ttIsqlのSET SERVEROUTPUT ON設定を使用している場合は、このプロシージャをコールする必要はありません。

構文

DBMS_OUTPUT.DISABLE;

ENABLEプロシージャ

このプロシージャは、PUT、PUT_LINE、NEW_LINE、GET_LINEおよびGET_LINESへのコールを有効にします。DBMS_OUTPUTパッケージが有効化されていない場合、これらのプロシージャへのコールは無視されます。

構文

DBMS_OUTPUT.ENABLE (
   buffer_size IN INTEGER DEFAULT 20000);

パラメータ

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

パラメータ説明

パラメータ	説明
`buffer_size`	バッファに入れられる情報量の上限(バイト) `buffer_size`に`NULL`を設定すると、制限がなくなります。

buffer_size

バッファに入れられる情報量の上限(バイト)

buffer_sizeにNULLを設定すると、制限がなくなります。

使用上のノート

ttIsqlからSET SERVEROUTPUT ONを使用する場合、このプロシージャをコールする必要はありません。これは自動的にコールされます(現在のリリースでは、buffer_sizeにNULL値が設定されています)。
ENABLEへのコールが複数ある場合、buffer_sizeは最後に指定された値になります。ユーザーがbuffer_size (NOT NULL)を指定した場合、最大サイズは1,000,000および最小サイズは2000です。
通常、NULLを選択することをお薦めします。デフォルトは、無制限のバッファをサポートしていなかった以前のデータベース・バージョンとの下位互換のために20000です。

GET_LINEプロシージャ

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

構文

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

パラメータ

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

パラメータ説明

パラメータ	説明
`line`	末尾の改行文字を除くバッファに入れられた単一行の情報 `「ORA-06502: PL/SQL: 数値または値のエラー: 文字列バッファが小さすぎます」`のリスクを回避するために、このパラメータを`VARCHAR2(32767)`として宣言する必要があります。
`status`	コール・ステータスコールが正常に完了すると、0が戻されます。バッファにこれ以上行がないと、1が戻されます。

line

末尾の改行文字を除くバッファに入れられた単一行の情報

「ORA-06502: PL/SQL: 数値または値のエラー: 文字列バッファが小さすぎます」のリスクを回避するために、このパラメータをVARCHAR2(32767)として宣言する必要があります。

status

コール・ステータス

コールが正常に完了すると、0が戻されます。バッファにこれ以上行がないと、1が戻されます。

使用上のノート

単一行または行の配列をバッファから取り出すことができます。バッファに入れられた単一行の情報を取り出すには、GET_LINEをコールします。サーバーへのコール数を減らすには、GET_LINESをコールして、バッファから行の配列を取り出します。
ttIsqlを使用している場合、特別なSET SERVEROUTPUT ONコマンドを使用することで、この情報を自動的に表示するように選択できます。
GET_LINEまたはGET_LINESをコールしてから、次にPUT、PUT_LINEまたはNEW_LINEをコールする前に取り出されなかった行は、次のメッセージとの混同を避けるために破棄されます。

GET_LINESプロシージャ

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

構文

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

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

パラメータ

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

パラメータ説明

パラメータ	説明
`lines`	バッファに入れられた情報の行の配列配列内の各行の最大長は32767バイトです。PL/SQL無名ブロックからプロシージャを実行する場合、3GLホスト・プログラムで可変長配列オーバーロード・バージョンを使用することをお薦めします。
`numlines`	バッファから取り出す行数プロシージャは、指定の行数を取り出した後、実際に取り出した行数を戻します。この数が要求した行数より少ない場合は、バッファにそれ以上行がない場合です。

lines

バッファに入れられた情報の行の配列

配列内の各行の最大長は32767バイトです。PL/SQL無名ブロックからプロシージャを実行する場合、3GLホスト・プログラムで可変長配列オーバーロード・バージョンを使用することをお薦めします。

numlines

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

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

使用上のノート

単一行または行の配列をバッファから取り出すことができます。バッファに入れられた単一行の情報を取り出すには、GET_LINEをコールします。サーバーへのトリップ数を減らすために、バッファから行の配列を取り出すには、GET_LINESをコールします。
ttIsqlを使用している場合、特別なSET SERVEROUTPUT ONコマンドを使用することで、この情報を自動的に表示するように選択できます。
GET_LINEまたはGET_LINESをコールしてから、次にPUT、PUT_LINEまたはNEW_LINEをコールする前に取り出されなかった行は、次のメッセージとの混同を避けるために廃棄されます。

NEW_LINEプロシージャ

このプロシージャは、行端マーカーを設定します。

GET_LINEプロシージャおよびGET_LINESプロシージャは、改行で区切られた行を返します。PUT_LINEプロシージャまたはNEW_LINEへのすべてのコールによって、GET_LINEまたはGET_LINESで返される行が生成されます。

構文

DBMS_OUTPUT.NEW_LINE;

PUTプロシージャ

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

ノート:

NUMBER入力を使用するPUTバージョンは非推奨になりました。これは、下位互換性を保つためにのみサポートされています。

構文

DBMS_OUTPUT.PUT (
    a IN VARCHAR2);

パラメータ

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

パラメータ	説明
`a`	バッファに設定する項目

使用上のノート

PUTを複数回コールすることによって個別に情報行を作成するか、PUT_LINEをコールして情報行全体をバッファに設定できます。
PUT_LINEをコールすると、指定した項目には行端マーカーが自動的に付きます。PUTをコールして行を作成する場合、NEW_LINEをコールして、独自の行端マーカーを追加する必要があります。GET_LINEおよびGET_LINESは、改行文字で終了していない行は戻しません。
行が行制限を超えた場合は、エラー・メッセージを受信します。
PUTまたはPUT_LINEで作成した出力はバッファに入れられます。この出力は、それをバッファに入れたPL/SQLプログラム・ユニットがコール元に戻るまで取り出せません。

例外

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

例外	説明
`ORA-20000`、`ORU-10027`	ENABLEプロシージャ・コールに指定した`buffer_size`制限に基づくバッファのオーバーフロー
`ORA-20000`、`ORU-10028`	行の長さのオーバーフロー(各行の制限は32767バイト)

PUT_LINEプロシージャ

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

ノート:

NUMBER入力を使用するPUT_LINEバージョンは非推奨になりました。これは、下位互換性を保つためにのみサポートされています。

構文

DBMS_OUTPUT.PUT_LINE (
   a IN VARCHAR2);

パラメータ

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

パラメータ	説明
`a`	バッファに設定する項目

使用上のノート

PUTを複数回コールすることによって個別に情報行を作成するか、PUT_LINEをコールして情報行全体をバッファに設定できます。
PUT_LINEをコールすると、指定した項目には行端マーカーが自動的に付きます。PUTをコールして行を作成する場合、NEW_LINEをコールして、独自の行端マーカーを追加する必要があります。GET_LINEおよびGET_LINESは、改行文字で終了していない行は戻しません。
行が行制限を超えた場合は、エラー・メッセージを受信します。
PUTまたはPUT_LINEで作成した出力はバッファに入れられます。この出力は、それをバッファに入れたPL/SQLプログラム・ユニットがコール元に戻るまで取り出せません。

例外

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

例外	説明
`ORA-20000`、`ORU-10027`	ENABLEプロシージャ・コールに指定した`buffer_size`制限に基づくバッファのオーバーフロー
`ORA-20000`、`ORU-10028`	行の長さのオーバーフロー(各行の制限は32767バイト)