DBMS_OUTPUT
パッケージを使用すると、ストアド・プロシージャおよびパッケージからメッセージを送信できます。このパッケージは、PL/SQLデバッグ情報を表示する場合に特に役立ちます。
この章の内容は次のとおりです。
概要
使用上の注意
ルールおよび制限
例外
例
表タイプ
この項では、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
が発生し、出力プロシージャから次のエラーが戻されることがあります。
通常、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つの表タイプが宣言されます。
注意:
|
表タイプ
このパッケージは、GET_LINESプロシージャとともに使用され、PUTプロシージャおよびPUT_LINEプロシージャを介して送信されたテキストを取得します。
構文
TYPE CHARARR IS TABLE OF VARCHAR2(32767) INDEX BY BINARY_INTEGER;
このパッケージは、GET_LINESプロシージャとともに使用され、PUTプロシージャおよびPUT_LINEプロシージャを介して送信されたテキストを取得します。
構文
TYPE DBMSOUTPUT_LINESARRAY IS VARRAY(2147483647) OF VARCHAR2(32767);
表4-2 DBMS_OUTPUTパッケージのサブプログラム
サブプログラム | 説明 |
---|---|
|
メッセージの出力を無効にします。 |
|
メッセージの出力を有効にします。 |
|
バッファから1行を取り出します。 |
|
バッファから行の配列を取り出します。 |
|
|
|
バッファに1行を格納します。 |
|
バッファに行の一部を格納します。 |
このプロシージャは、PUT
、PUT_LINE
、NEW_LINE
、GET_LINE
およびGET_LINES
へのコールを無効にし、バッファに残っている情報をパージします。
ENABLEプロシージャと同様に、ttIsql
のSET SERVEROUTPUT ON
設定を使用している場合は、このプロシージャをコールする必要はありません。
構文
DBMS_OUTPUT.DISABLE;
このプロシージャは、PUT
、PUT_LINE
、NEW_LINE
、GET_LINE
およびGET_LINES
へのコールを有効にします。DBMS_OUTPUT
パッケージが有効化されていない場合、これらのプロシージャへのコールは無視されます。
構文
DBMS_OUTPUT.ENABLE (
buffer_size IN INTEGER DEFAULT 20000);
パラメータ
表4-3 ENABLEプロシージャ・パラメータ
パラメータ | 説明 |
---|---|
|
バッファに入れられる情報量の上限(バイト)
|
使用上の注意
ttIsql
からSET SERVEROUTPUT ON
を使用する場合、このプロシージャをコールする必要はありません。これは自動的にコールされます(現在のリリースでは、buffer_size
にNULL
値が設定されています)。
ENABLE
へのコールが複数ある場合、buffer_size
は最後に指定された値になります。ユーザーがbuffer_size
(NOT
NULL
)を指定した場合、最大サイズは1,000,000および最小サイズは2000です。
通常、NULL
を選択することをお薦めします。デフォルトは、無制限のバッファをサポートしていなかった以前のデータベース・バージョンとの下位互換のために20000です。
このプロシージャは、バッファに入れられた単一行の情報を取り出します。
構文
DBMS_OUTPUT.GET_LINE ( line OUT VARCHAR2, status OUT INTEGER);
パラメータ
表4-4 GET_LINEプロシージャ・パラメータ
パラメータ | 説明 |
---|---|
|
末尾の改行文字を除くバッファに入れられた単一行の情報
|
|
コール・ステータス コールが正常に完了すると、0が戻されます。バッファにこれ以上行がないと、1が戻されます。 |
使用上の注意
単一行または行の配列をバッファから取り出すことができます。バッファに入れられた単一行の情報を取り出すには、GET_LINE
をコールします。サーバーへのコール数を減らすには、GET_LINES
をコールして、バッファから行の配列を取り出します。
ttIsql
を使用している場合、特別なSET
SERVEROUTPUT
ON
コマンドを使用することで、この情報を自動的に表示するように選択できます。
GET_LINE
またはGET_LINES
をコールしてから、次にPUT
、PUT_LINE
またはNEW_LINE
をコールする前に取り出されなかった行は、次のメッセージとの混同を避けるために破棄されます。
このプロシージャは、バッファから行の配列を取り出します。
構文
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プロシージャのパラメータ
パラメータ | 説明 |
---|---|
|
バッファに入れられた情報の行の配列 配列内の各行の最大長は32767バイトです。PL/SQL無名ブロックからプロシージャを実行する場合、3GLホスト・プログラムで可変長配列オーバーロード・バージョンを使用することをお薦めします。 |
|
バッファから取り出す行数 プロシージャは、指定の行数を取り出した後、実際に取り出した行数を戻します。この数が要求した行数より少ない場合は、バッファにそれ以上行がない場合です。 |
使用上の注意
単一行または行の配列をバッファから取り出すことができます。バッファに入れられた単一行の情報を取り出すには、GET_LINE
をコールします。サーバーへのトリップ数を減らすために、バッファから行の配列を取り出すには、GET_LINES
をコールします。
ttIsql
を使用している場合、特別なSET
SERVEROUTPUT
ON
コマンドを使用することで、この情報を自動的に表示するように選択できます。
GET_LINE
またはGET_LINES
をコールしてから、次にPUT
、PUT_LINE
またはNEW_LINE
をコールする前に取り出されなかった行は、次のメッセージとの混同を避けるために廃棄されます。
このプロシージャは、行端マーカーを設定します。GET_LINEプロシージャおよびGET_LINESプロシージャは、改行で区切られた行を戻します。PUT_LINEプロシージャまたはNEW_LINE
へのすべてのコールによって、GET_LINE
またはGET_LINES
で戻される行が生成されます。
構文
DBMS_OUTPUT.NEW_LINE;
このプロシージャは、行の一部をバッファに設定します。
注意: NUMBER 入力を使用するPUT バージョンは非推奨になりました。これは、下位互換性を保つためにのみサポートされています。 |
構文
DBMS_OUTPUT.PUT (
a IN VARCHAR2);
パラメータ
使用上の注意
PUT
を複数回コールすることによって個別に情報行を作成するか、PUT_LINE
をコールして情報行全体をバッファに設定することができます。
PUT_LINE
をコールすると、指定した項目には行端マーカーが自動的に付きます。PUT
をコールして行を作成する場合、NEW_LINE
をコールして、独自の行端マーカーを追加する必要があります。GET_LINE
およびGET_LINES
は、改行文字で終了していない行は戻しません。
行が行制限を超えた場合は、エラー・メッセージを受信します。
PUT
またはPUT_LINE
で作成した出力はバッファに入れられます。この出力は、それをバッファに入れたPL/SQLプログラム・ユニットがコール元に戻るまで取り出せません。
例外
表4-7 PUTプロシージャの例外
例外 | 説明 |
---|---|
|
ENABLEプロシージャ・コールに指定した |
|
行の長さのオーバーフロー(各行の制限は32767バイト) |
このプロシージャは、行をバッファに設定します。
注意: NUMBER 入力を使用するPUT_LINE バージョンは非推奨になりました。これは、下位互換性を保つためにのみサポートされています。 |
構文
DBMS_OUTPUT.PUT_LINE (
a IN VARCHAR2);
パラメータ
使用上の注意
PUT
を複数回コールすることによって個別に情報行を作成するか、PUT_LINE
をコールして情報行全体をバッファに設定することができます。
PUT_LINE
をコールすると、指定した項目には行端マーカーが自動的に付きます。PUT
をコールして行を作成する場合、NEW_LINE
をコールして、独自の行端マーカーを追加する必要があります。GET_LINE
およびGET_LINES
は、改行文字で終了していない行は戻しません。
行が行制限を超えた場合は、エラー・メッセージを受信します。
PUT
またはPUT_LINE
で作成した出力はバッファに入れられます。この出力は、それをバッファに入れたPL/SQLプログラム・ユニットがコール元に戻るまで取り出せません。
例外
表4-9 PUT_LINEプロシージャの例外
例外 | 説明 |
---|---|
|
ENABLEプロシージャ・コールに指定した |
|
行の長さのオーバーフロー(各行の制限は32767バイト) |