| Oracle® Database PL/SQLパッケージおよびタイプ・リファレンス 11g リリース2(11.2) B56262-06 |
|
 前 |
 次 |
DBMS_DEBUGは、OracleサーバーにおけるPL/SQLデバッガ・レイヤー、プローブに対するPL/SQLインタフェースです。
このAPIは、主にサーバー側のデバッガを実装することを目的としており、サーバー側のPL/SQLプログラム・ユニットをデバッグする方法を提供します。
|
注意: プログラム・ユニットという用語は、各種のPL/SQLプログラム(プロシージャ、ファンクション、パッケージ、パッケージ本体、トリガー、無名ブロック、オブジェクト・タイプまたはオブジェクト・タイプ本体)のことを指します。 |
この章では、次の項目について説明します。
概要
定数
変数
例外
使用上の注意
レコード・タイプ
表タイプ
サーバー側のコードをデバッグするには、2つのデータベース・セッションが必要です。1つはコードをデバッグ・モードで実行するセッション(ターゲット・セッション)、他の1つはそのターゲット・セッションを監視するセッション(デバッグ・セッション)です。
ターゲット・セッションは、DBMS_DEBUGで初期化コールを行うことでデバッグ可能になります。これにより、そのセッションにマークが付けられるため、PL/SQLインタプリタがデバッグ・モードで実行され、デバッグ・イベントが生成されます。デバッグ・イベントが生成されると、それらはセッションから転送されます。ほとんどの場合、デバッグ・イベントには戻り通知が必要なため、インタプリタは応答があるまで一時停止します。
この間に、デバッグ・セッション自体はDBMS_DEBUGを使用して初期化する必要があり、これによって、監視するターゲット・セッションが識別されます。次に、デバッグ・セッションはDBMS_DEBUGのエントリ・ポイントをコールして、ターゲット・セッションから転送されたイベントを読み込み、ターゲット・セッションと通信します。
次のサブプログラムは、ターゲット・セッション(デバッグ対象のセッション)で実行されます。
DBMS_DEBUGは、PL/SQLコンパイラへのインタフェースは提供しませんが、コンパイラがオプションで生成するデバッグ情報には依存します。デバッグ情報がないと、パラメータまたは変数の値の検証や変更を実行できません。
ブレーク・ポイントの状態には次の値があります。
breakpoint_status_unused: ブレーク・ポイントは使用されていません。
ブレーク・ポイントが使用されている場合、状態は次の値のマスクになります。
breakpoint_status_active: 行ブレーク・ポイント。
breakpoint_status_disabled: ブレーク・ポイントは現在使用できません。
breakpoint_status_remote: shadowブレーク・ポイント(リモート・ブレーク・ポイントのローカル表示)
この値は、デバッグ・セッション(SYNCHRONIZE、CONTINUE、SET_BREAKPOINTなど)でコールされる様々なファンクションによって戻されます。PL/SQL例外がクライアント/サーバーおよびサーバー/サーバーの境界を越えて発生した場合は、すべて例外となり、エラー・コードは戻されません。
| 値 | 説明 |
|---|---|
success |
正常終了 |
GET_VALUEおよびSET_VALUEによって戻されるステータスは次のとおりです。
| ステータス | 説明 |
|---|---|
error_bogus_frame |
該当するエントリポイントがスタックにありません。 |
error_no_debug_info |
プログラムがデバッグ記号なしにコンパイルされました。 |
error_no_such_object |
該当する変数またはパラメータがありません。 |
error_unknown_type |
デバッグ情報を読み取れません。 |
error_indexed_table |
オブジェクトが表で、索引が提供されていない場合にGET_VALUEで戻されます。 |
error_illegal_index |
該当する要素がコレクション内に存在しません。 |
error_nullcollection |
表がアトミックNULLです。 |
error_nullvalue |
値がNULLです。 |
SET_VALUEによって戻されるステータスは次のとおりです。
| ステータス | 説明 |
|---|---|
error_illegal_value |
制約違反。 |
error_illegal_null |
制約違反。 |
error_value_malformed |
指定された値を解読できません。 |
error_other |
その他のエラー。 |
error_name_incomplete |
名前をスカラーに変換できません。 |
ブレーク・ポイント・ファンクションによって戻されるステータスは次のとおりです。
| ステータス | 説明 |
|---|---|
error_no_such_breakpt |
該当するブレーク・ポイントがありません。 |
error_idle_breakpt |
未使用のブレーク・ポイントは使用可能または使用禁止にできません。 |
error_bad_handle |
指定されたプログラムにブレーク・ポイントを設定できません(存在していないか、またはセキュリティ違反です)。 |
一般的なエラー・コード(多数のDBMS_DEBUGサブプログラムが戻す)は次のとおりです。
| ステータス | 説明 |
|---|---|
error_unimplemented |
機能が実装されていません。 |
error_deferred |
プログラムが実行されていません。操作は延期されました。 |
error_exception |
サーバー上のDBMS_DEBUGまたはプローブ・パッケージで例外が発生しました。 |
error_communication |
タイムアウト以外のエラーが発生しました。 |
error_timeout |
タイムアウトが発生しました。 |
| 例外 | 説明 |
|---|---|
illegal_init |
INITIALIZEの前にDEBUG_ONがコールされました。 |
次の例外は、プロシージャSELF_CHECKによって発生します。
| 例外 | 説明 |
|---|---|
pipe_creation_failure |
パイプを作成できませんでした。 |
pipe_send_failure |
パイプにデータを書き込めませんでした。 |
pipe_receive_failure |
パイプからデータを読み込めませんでした。 |
pipe_datatype_mismatch |
パイプ内のデータ・タイプが正しくありませんでした。 |
pipe_data_error |
データがパイプ内で混同されていました。 |
デバッグ情報の生成を確認する方法は2通りあります。セッション・スイッチを使用する方法と、個別に再コンパイルする方法です。
セッション・スイッチを設定するには、次の文を入力します。
ALTER SESSION SET PLSQL_DEBUG = true;
この文によって、コンパイラはセッションの残りの部分に関するデバッグ情報を生成します。既存のPL/SQLは再コンパイルしません。
既存のPL/SQLコードのデバッグ情報を生成するには、次の文のいずれかを使用します(2番目の文はパッケージまたはタイプの本体を再コンパイルします)。
ALTER [PROCEDURE | FUNCTION | PACKAGE | TRIGGER | TYPE] <name> COMPILE DEBUG; ALTER [PACKAGE | TYPE] <name> COMPILE DEBUG BODY;
図52-1および図52-2に、デバッグ対象のセッションおよびデバッグ・セッションでの操作のフローを示します。
インタプリタは、次の場合に実行を一時停止します。
インタプリタの起動時。実行前に、遅延ブレーク・ポイントをインストールできるようにするため。
使用可能なブレーク・ポイントを含んだ行に達したとき。
関連のあるイベントが発生した行に達したとき。関連イベントのセットは、breakflagsパラメータのDBMS_DEBUG.CONTINUEに渡されるフラグで指定します。
セッション終了のイベントはありません。したがって、ターゲット・セッションが終了していないことを、デバッグ・セッションでチェックして確認する必要があります。ターゲット・セッションが終了した後にDBMS_DEBUG.SYNCHRONIZEをコールすると、タイムアウトするまでデバッグ・セッションがハングアップします。
図では、ターゲット・セッションの前にブレーク・ポイントを設定できることが示されています。これは確かに可能です。この場合、プローブはブレーク・ポイント要求をキャッシュして、最初の同期でターゲット・セッションに送信します。ただし、ブレーク・ポイント要求がこのように遅延した場合は次のようになります。
SET_BREAKPOINTはブレーク・ポイント番号を設定しません(必要に応じて後でSHOW_BREAKPOINTSから取得できます)。
SET_BREAKPOINTはブレーク・ポイント要求を検証しません。要求されたソース行が存在しない場合は、同期時にエラーが内部的に発生し、ブレーク・ポイントは設定されません。
プローブをデバッグするために、DBMS_DEBUGのコールの一部に対してdiagnosticsパラメータが用意されています。これらのパラメータは、RDBMSトレース・ファイルに診断出力を格納するかどうかを指定します。RDBMSトレース・ファイルに出力できない場合、このパラメータは無効になります。
PL/SQLプログラム内で宣言される例外は、ユーザー定義の例外として認識されています。さらに、Oracleカーネルから戻されるOracleエラー(OER)があります。この2つのメカニズムを結合するために、PL/SQLはユーザー定義の例外をOERに変換するexception_initプラグマを提供していて、この処理にはPL/SQLハンドラが使用され、PL/SQLエンジンは、OERをOracleカーネルに戻すことができます。現行のリリースでは、OERに関する使用可能な情報はその番号のみです。2つのユーザー定義例外が同じOERにexception_initされると、区別できません。
サーバー上のプログラム・ユニットは、異なるネームスペースに常駐しています。ブレーク・ポイントの設定時には、希望するネームスペースを指定してください。
Namespace_cursorにはカーソル(無名ブロック)が含まれています。
Namespace_pgkspec_or_toplevelには次が含まれています。
パッケージ仕様部
他のパッケージ、プロシージャまたはファンクション内にネストされていないプロシージャおよびファンクション
オブジェクト・タイプ
Namespace_pkg_bodyにはパッケージ本体およびタイプ本体が含まれています。
Namespace_triggerにはトリガーが含まれています。
この値は、特定のネームスペースのオブジェクトを一意化するために使用されます。これらの定数は、プローブがスタックのバックトレースを提供しているときに、PROGRAM_INFOで使用されます。
LibunitType_cursor
LibunitType_procedure
LibunitType_function
LibunitType_package
LibunitType_package_body
LibunitType_trigger
LibunitType_Unknown
この値は、クライアントに関連のあるイベントをプローブに通知するために、CONTINUEに対するbreakflagsパラメータで使用されます。これらのフラグは結合できます。
| 値 | 説明 |
|---|---|
break_next_line |
次のソース行でブレークします(コールをスキップ)。 |
break_any_call |
次のソース行でブレークします(コールを開始)。 |
break_any_return |
現行のエントリポイントから戻された後ブレーク(現行のルーチンからコールされたエントリポイントはすべてスキップ)します。 |
break_return |
次回のエントリポイントが戻し処理の準備ができた時点でブレークします。(現行のエントリポイントからコールされたエントリポイントが含まれます。インタプリタがProc2をコールするProc1を実行している場合、break_returnはProc2の終了時に停止します。) |
break_exception |
例外が発生したときにブレークします。 |
break_handler |
例外ハンドラが実行されたときにブレークします。 |
abort_execution |
実行を停止し、DBMS_DEBUG.CONTINUEがコールされるとすぐに、'exit'イベントを強制的に実行します。 |
このフラグは、info_requestedパラメータとしてSYNCHRONIZE、CONTINUEおよびGET_RUNTIME_INFOに渡されます。
| フラグ | 説明 |
|---|---|
info_getStackDepth |
スタックの現在の深さを取得します。 |
info_getBreakpoint |
ブレーク・ポイント数を取得します。 |
info_getLineinfo |
プログラム・ユニット情報を取得します。 |
CONTINUEの実行後、プログラムは最後まで実行されるか、または途中の行でブレークします。
| 理由 | 説明 |
|---|---|
reason_none |
- |
reason_interpreter_starting |
インタプリタは起動中です。 |
reason_breakpoint |
ブレーク・ポイントに到達しました。 |
reason_enter |
プロシージャ・エントリ。 |
reason_return |
プロシージャが戻ります。 |
reason_finish |
プロシージャが終了しました。 |
reason_line |
改行に到達しました。 |
reason_interrupt |
割込みが発生しました。 |
reason_exception |
例外が発生しました。 |
reason_exit |
インタプリタは終了処理中です(旧形式)。 |
reason_knl_exit |
カーネルは終了処理中です。 |
reason_handler |
例外ハンドラを起動します。 |
reason_timeout |
タイムアウトが発生しました。 |
reason_instantiate |
インスタンス化ブロック。 |
reason_abort |
インタプリタは異常終了中です。 |
DBMS_DEBUGパッケージでは、レコード・タイプおよび表タイプを定義します。
このタイプは、ブレーク・ポイントに関して、現在の状態や配置されたプログラム・ユニットなどの情報を提供します。
構文
TYPE breakpoint_info IS RECORD ( name VARCHAR2(30), owner VARCHAR2(30), dblink VARCHAR2(30), line# BINARY_INTEGER, libunittype BINARY_INTEGER, status BINARY_INTEGER);
フィールド
表52-2 BREAKPOINT_INFOフィールド
| フィールド | 説明 |
|---|---|
|
|
プログラム・ユニットの名前。 |
|
|
プログラム・ユニットの所有者。 |
|
|
データベース・リンク(リモートの場合)。 |
|
|
行番号。 |
|
|
ネストされたプロシージャまたはファンクション以外は |
|
|
|
このタイプはプログラムの位置を指定します。これはプログラム・ユニット内の行番号です。これは、スタックのバックトレース用およびブレーク・ポイントの設定と検査用に使用されます。読取り専用フィールドは、ブレーク・ポイント操作に関してプローブでは現在は無視されています。読取り専用フィールドは、プローブによってスタックのバックトレース用のみに設定されます。
構文
TYPE program_info IS RECORD(
-- The following fields are used when setting a breakpoint
namespace BINARY_INTEGER,
name VARCHAR2(30),
owner VARCHAR2(30),
dblink VARCHAR2(30),
line# BINARY_INTEGER,
-- Read-only fields (set by Probe when doing a stack backtrace)
libunittype BINARY_INTEGER,
entrypointname VARCHAR2(30));
フィールド
表52-3 PROGRAM_INFOのフィールド
| フィールド | 説明 |
|---|---|
|
|
「ネームスペース」を参照してください。 |
|
|
プログラム・ユニットの名前。 |
|
|
プログラム・ユニットの所有者。 |
|
|
データベース・リンク(リモートの場合)。 |
|
|
行番号。 |
|
|
読取り専用フィールド。ネストされたプロシージャまたはファンクション以外は |
|
|
読取り専用フィールド。同じネームスペースを共有するオブジェクト(プロシージャやパッケージ仕様部など)を一意化します。 詳細は、「Libunitタイプ」を参照してください。 |
このタイプは、実行プログラムに関するコンテキスト情報を提供します。
表52-5 DBMS_DEBUGパッケージのサブプログラム
| サブプログラム | 説明 |
|---|---|
|
|
デバッグ・セッションにターゲット・デバッグIDに関する情報を通知します。 |
|
|
ターゲット・プログラムの実行を継続します。 |
|
|
デバッグ・モードをオフにします。 |
|
|
デバッグ・モードをオンにします。 |
|
|
ブレーク・ポイントを削除します。 |
|
|
OERブレーク・ポイントを削除します。 |
|
|
ターゲット・プログラムのデバッグを停止します。 |
|
|
ブレーク・ポイントを使用禁止にします。 |
|
|
既存のブレーク・ポイントをアクティブにします。 |
|
|
ターゲット・セッションでSQLまたはPL/SQLを実行します。 |
|
|
索引表に対する一連の索引を戻します。 |
|
|
SHOW_SOURCEの使用時に、バッファ・オーバーフローが起きたときに追加ソースを提供します。 |
|
|
プログラム・ユニット内の行番号に関する情報を戻します。 |
|
|
現行のプログラムに関する情報を戻します。 |
|
|
現行のタイムアウト動作を戻します。 |
|
|
現在実行中のプログラムから値を取得します。 |
|
|
ターゲット・セッションのデバッグIDを設定します。 |
|
|
ターゲット・セッションがタイムアウトしないようにpingします。 |
|
|
スタックのバックトレースを印刷します。 |
|
|
スタックのバックトレースを印刷します。 |
|
|
サーバー上の |
|
|
内部一貫性チェックを実行します。 |
|
|
プログラム・ユニットにブレーク・ポイントを設定します。 |
|
|
OERブレーク・ポイントを設定します。 |
|
|
タイムアウト値を設定します。 |
|
|
タイムアウトの発生時に、ターゲット・セッションに行う処理をプローブに指示します。 |
|
|
現在実行中のプログラムに値を設定します。 |
|
|
現行のブレーク・ポイントのリストを戻します。 |
|
|
フレーム・ソースをフェッチします。 |
|
|
プログラム・ソースをフェッチします。 |
|
|
プログラムの実行開始を待機します。 |
|
|
ターゲット・セッションが現在ストアド・プロシージャを実行中の場合は |
このファンクションは、指定されたブレーク・フラグ(関連のあるイベントのマスク)をターゲット・プロセスのプローブに渡します。プローブに、ターゲット・プロセスの実行を継続するように通知し、ターゲット・プロセスが実行を終了するか、またはイベントを通知するまで待機します。
info_requestedがNULLでない場合は、GET_RUNTIME_INFOをコールします。
構文
DBMS_DEBUG.CONTINUE ( run_info IN OUT runtime_info, breakflags IN BINARY_INTEGER, info_requested IN BINARY_INTEGER := NULL) RETURN BINARY_INTEGER;
パラメータ
表52-7 CONTINUEファンクションのパラメータ
| パラメータ | 説明 |
|---|---|
|
|
プログラムの状態に関する情報。 |
|
|
関連のあるイベントのマスク(「ブレーク・フラグ」を参照)。 |
|
|
プログラムが停止したときに、 |
|
注意: immediateが |
このプロシージャは、そのセッションでデバッグを実行する必要がなくなったことをターゲット・セッションに通知します。セッションの終了前にこのファンクションをコールする必要はありません。
このプロシージャは、すべてのPL/SQLがデバッグ・モードで実行されるように、ターゲット・セッションにマークを設定します。この処理は、デバッグの開始前に実行する必要があります。
このプロシージャは、ターゲット・プログラムのデバッグを停止します。このプロシージャはいつでもコール可能ですが、デバッグ・セッションの連結が解除されたことはターゲット・セッションに通知されず、ターゲット・セッションの実行は終了しません。したがって、ターゲット・セッションが独自にハングアップしないように注意してください。
このプロシージャは、ターゲット・セッションでSQLまたはPL/SQLコードを実行します。ターゲット・セッションは、ブレーク・ポイント(またはその他のイベント)で待機中であるとみなされます。デバッグ・セッションでDBMS_DEBUG.EXECUTEがコールされ、ターゲット・セッションにコードの実行を要求します。
構文
DBMS_DEBUG.EXECUTE ( what IN VARCHAR2, frame# IN BINARY_INTEGER, bind_results IN BINARY_INTEGER, results IN OUT NOCOPY dbms_debug_vc2coll, errm IN OUT NOCOPY VARCHAR2);
例
例1
この例はSQL文の実行例です。結果は戻されません。
DECLARE
coll sys.dbms_debug_vc2coll; -- results (unused)
errm VARCHAR2(100);
BEGIN
dbms_debug.execute('insert into emp(ename,empno,deptno) ' ||
'values(''LJE'', 1, 1)',
-1, 0, coll, errm);
END;
例2
この例はPL/SQLブロックの実行例で、結果は戻されません。ブロックは自律型トランザクションで、表に挿入された値はデバッグ・セッションで参照できます。
DECLARE
coll sys.dbms_debug_vc2coll;
errm VARCHAR2(100);
BEGIN
dbms_debug.execute(
'DECLARE PRAGMA autonomous_transaction; ' ||
'BEGIN ' ||
' insert into emp(ename, empno, deptno) ' ||
' values(''LJE'', 1, 1); ' ||
' COMMIT; ' ||
'END;',
-1, 0, coll, errm);
END;
例3
この例はPL/SQLブロックの実行例で、結果がいくつか戻されます。
DECLARE
coll sys.dbms_debug_vc2coll;
errm VARCHAR2(100);
BEGIN
dbms_debug.execute(
'DECLARE ' ||
' pp SYS.dbms_debug_vc2coll := SYS.dbms_debug_vc2coll(); ' ||
' x PLS_INTEGER; ' ||
' i PLS_INTEGER := 1; ' ||
'BEGIN ' ||
' SELECT COUNT(*) INTO x FROM emp; ' ||
' pp.EXTEND(x * 6); ' ||
' FOR c IN (SELECT * FROM emp) LOOP ' ||
' pp(i) := ''Ename: '' || c.ename; i := i+1; ' ||
' pp(i) := ''Empno: '' || c.empno; i := i+1; ' ||
' pp(i) := ''Job: '' || c.job; i := i+1; ' ||
' pp(i) := ''Mgr: '' || c.mgr; i := i+1; ' ||
' pp(i) := ''Sal: '' || c.sal; i := i+1; ' ||
' pp(i) := null; i := i+1; ' ||
' END LOOP; ' ||
' :1 := pp;' ||
'END;',
-1, 1, coll, errm);
each := coll.FIRST;
WHILE (each IS NOT NULL) LOOP
dosomething(coll(each));
each := coll.NEXT(each);
END LOOP;
END;
変数またはパラメータの名前を指定すると、索引表の場合はその一連の索引を戻します。索引表以外の場合はエラーが戻されます。
構文
DBMS_DEBUG.GET_INDEXES ( varname IN VARCHAR2, frame# IN BINARY_INTEGER, handle IN program_info, entries OUT index_table) RETURN BINARY_INTEGER;
フォーマット済バッファを生成したSHOW_SOURCEプロシージャの該当バージョンによって提供されたバッファにソースが収まらない場合、このプロシージャが追加ソースを提供します。
構文
DBMS_DEBUG.GET_MORE_SOURCE ( buffer IN OUT VARCHAR2, buflen IN BINARY_INTEGER, piece# IN BINARY_INTEGER);
パラメータ
表52-20 GET_MORE_SOURCEプロシージャのパラメータ
| パラメータ | 説明 |
|---|---|
|
|
バッファ |
|
|
バッファの長さ |
|
|
2とSHOW_SOURCEプロシージャの適切なバージョンへのコールからパラメータの各部分に戻された値との間の値 |
このファンクションは、ブレーク・ポイントを配置できるソース行をデバッガが決定できるように、プログラムに関する行およびエントリポイントの情報を検索します。
構文
DBMS_DEBUG.GET_LINE_MAP ( program IN program_info, maxline OUT BINARY_INTEGER, number_of_entry_points OUT BINARY_INTEGER, linemap OUT RAW) RETURN BINARY_INTEGER;
パラメータ
表52-21 GET_LINE_MAPファンクションのパラメータ
| パラメータ | 説明 |
|---|---|
|
|
トップレベルのプログラム・ユニット(プロシージャ、パッケージ、ファンクション、パッケージ本体など)。 |
|
|
'program'内で最大のソース・コード行番号。 |
|
|
'program'内のサブプログラムの数。 |
|
|
'program'の実行可能行を表すビットマップ。行番号Nが実行可能である場合、ビット番号N MOD 8がラインマップ位置N / 8で1に設定されます。戻されるラインマップの長さは、 |
このファンクションは、現行のプログラムに関する情報を戻します。これは、SYNCHRONIZEまたはCONTINUEに対するinfo_requestedパラメータが0 (ゼロ)に設定された場合にのみ必要です。
|
注意: このファンクションは、現在クライアント側のPL/SQLでのみ使用されます。 |
構文
DBMS_DEBUG.GET_RUNTIME_INFO ( info_requested IN BINARY_INTEGER, run_info OUT runtime_info) RETURN BINARY_INTEGER;
パラメータ
表52-23 GET_RUNTIME_INFOファンクションのパラメータ
| パラメータ | 説明 |
|---|---|
|
|
プログラムが停止したときに、 |
|
|
プログラムの状態に関する情報。 |
このファンクションは、現在実行中のプログラムから値を取得します。GET_VALUEファンクションは、2種類オーバーロードされています。
構文
DBMS_DEBUG.GET_VALUE ( variable_name IN VARCHAR2, frame# IN BINARY_INTEGER, scalar_value OUT VARCHAR2, format IN VARCHAR2 := NULL) RETURN BINARY_INTEGER;
戻り値
表52-27 GET_VALUEファンクションの戻り値
| 戻り値 | 説明 |
|---|---|
|
|
正常な完了。 |
|
|
フレームが存在しません。 |
|
|
エントリポイントにデバッグ情報がありません。 |
|
|
|
|
|
デバッグ情報内のタイプ情報が判読不能です。 |
|
|
値が |
|
|
オブジェクトは表ですが、索引が提供されていません。 |
次のGET_VALUE構文は、パッケージ変数フェッチ用です。フレーム番号のかわりに、変数を含んだパッケージを説明するハンドルを使用します。
構文
DBMS_DEBUG.GET_VALUE ( variable_name IN VARCHAR2, handle IN program_info, scalar_value OUT VARCHAR2, format IN VARCHAR2 := NULL) RETURN BINARY_INTEGER;
例
この例は、スキーマSCOTT内の変数VARを含んだ任意のパッケージPACKの値を取得する方法を示しています。
DECLARE
handle dbms_debug.program_info;
resultbuf VARCHAR2(500);
retval BINARY_INTEGER;
BEGIN
handle.Owner := 'SCOTT';
handle.Name := 'PACK';
handle.namespace := dbms_debug.namespace_pkgspec_or_toplevel;
retval := dbms_debug.get_value('VAR', handle, resultbuf, NULL);
END;
このファンクションは、デバッグ用にターゲット・セッションを初期化します。
構文
DBMS_DEBUG.INITIALIZE ( debug_session_id IN VARCHAR2 := NULL, diagnostics IN BINARY_INTEGER := 0) RETURN VARCHAR2;
使用上の注意
DBMS_DEBUGとJDWPベースのデバッグ・インタフェースは同時に使用できません。このコールは、セッションが現在JDWPベースのデバッグ・インタフェースでデバッグ中の場合はORA-30677エラーが表示されて失敗するか、またはコールが成功したとしても、さらにJDWPベースのインタフェースを使用してこのセッションをデバッグすることはできません。
DBMS_DEBUGへのコールは、コール元または指定されたデバッグ・ロールがDEBUG CONNECT SESSION権限を有する場合のみ成功します。失敗した場合は、ORA-1031エラーが表示されます。他に起こりうる例外として、デバッグ・ロールが指定されてもパスワードが一致しない場合、コール元のユーザーがロールを権限付与されていない場合またはロールがアプリケーション起動型であるのにこのコールがロール起動パッケージ内から発生していない場合などもあります。
CREATE ANY PROCEDURE権限は、デバッガによるルーチンの可視性には影響を与えません。各オブジェクトへの権限DEBUGは、対応するDEBUG ANY PROCEDUREの変数を使用して導入されています。これは、セッションのログイン・ユーザー以外のユーザーが所有するルーチンを確認するために必要です。
デバッグ・ロールの認証およびDEBUG CONNECT SESSION権限のチェックは、このルーチンへのコール元のコンテキストの中で行われます。コール元が定義者権限ルーチンであるか、または定義者権限ルーチンからコールされている場合、定義ユーザー、デバッグ・ロールまたはPUBLICに付与された権限のみがDEBUG CONNECT SESSIONのチェックに使用されます。このコールが定義者権限ルーチン内からのものであると、デバッグ・ロールが指定される場合は、その定義者に付与されたものである必要がありますが、セッション・ログイン・ユーザーに付与されたものである必要はなく、またコールが行われる際のコール・セッションで有効にする必要もありません。
このコールを実行した後で、デバッガによって行われる、個々のプロシージャ上でDEBUG権限を検索するチェックは、セッションのログイン・ユーザー、このコールが行われた瞬間のセッション・レベルで使用可能になったロール(そのロールがコールの定義者権限環境内で使用できない場合でも同様)およびデバッグ・ロールのコンテキストで行われます。
このプロシージャは、ターゲット・セッションがタイムアウトしないようにpingします。ターゲット・セッションで実行が中断したとき、ブレーク・ポイントなどでこのプロシージャを使用します。
timeout_behaviourがretry_on_timeoutに設定されている場合、このプロシージャは不要です。
使用上の注意
ターゲット・セッションのタイムアウト・オプションは、set_timeout_behaviourをコールすることによってターゲット・セッションに登録されます。
retry_on_timeout: 再試行します。タイムアウトの効果はありません。timeoutに無限に大きい値を設定した場合と同じです。
continue_on_timeout: 同じイベント・フラグを使用して、実行を継続します。
nodebug_on_timeout: debug-modeをオフにして(つまり、debug_offをコール)、実行を継続します。debug_onをコールして初期化しなおさないかぎり、これ以降、このターゲット・セッションでイベントは生成されません。
abort_on_timeout: abort_executionフラグを使用して実行を継続しますが、これにより、プログラムは即時に終了します。セッションはデバッグ・モードのままです。
retry_on_timeout CONSTANT BINARY_INTEGER:= 0;
continue_on_timeout CONSTANT BINARY_INTEGER:= 1;
nodebug_on_timeout CONSTANT BINARY_INTEGER:= 2;
abort_on_timeout CONSTANT BINARY_INTEGER:= 3;
このプロシージャは、現在の実行スタックのバックトレース・リストを出力します。これは、プログラムが実行中の場合のみコールしてください。
PRINT_BACKTRACEプロシージャは、2種類オーバーロードされています。
このプロシージャは、内部一貫性チェックを実行します。SELF_CHECKは、プローブ・プロセスが通信可能かどうかを確認するために、通信テストも実行します。
SELF_CHECKが正常に終了しなかった場合は、このサーバーにインストールされているDBMS_DEBUGのバージョンが適切ではない可能性があります。解決方法は、正しいバージョンをインストールすることです(pbload.sqlを実行すると、DBMS_DEBUGおよびその他の関連パッケージがロードされます)。
例外
表52-35 SELF_CHECKプロシージャの例外
| 例外 | 説明 |
|---|---|
|
|
プローブのバージョンに一貫性がありません。 |
|
|
パイプを作成できませんでした。 |
|
|
パイプにデータを書き込めませんでした。 |
|
|
パイプからデータを読み込めませんでした。 |
|
|
パイプ内のデータ・タイプが正しくありませんでした。 |
|
|
データがパイプ内で混同されていました。 |
これらはすべて致命的な例外です。プローブの正常な実行を妨げる重大な問題であることを示しています。
このファンクションは、現行セッションを持続するためのブレーク・ポイントをプログラム・ユニットに設定します。ターゲット・プログラムがブレーク・ポイントに到達すると、実行は一時停止します。
構文
DBMS_DEBUG.SET_BREAKPOINT ( program IN program_info, line# IN BINARY_INTEGER, breakpoint# OUT BINARY_INTEGER, fuzzy IN BINARY_INTEGER := 0, iterations IN BINARY_INTEGER := 0) RETURN BINARY_INTEGER;
パラメータ
表52-36 SET_BREAKPOINTファンクションのパラメータ
| パラメータ | 説明 |
|---|---|
|
|
ブレーク・ポイントが設定されるプログラム・ユニットに関する情報。(バージョン2.1以上では、ネームスペース、名前、所有者およびdblinkを |
|
|
ブレーク・ポイントが設定される行。 |
|
|
正常に完了すると、ブレーク・ポイントを参照するための一意のブレーク・ポイント番号が含まれます。 |
|
|
指定した行に実行可能コードがない場合にのみ適用されます。 0(ゼロ)の場合は、 1の場合は、ブレーク・ポイントを設定する行が指定行から順方向に検索されます。 -1の場合は、ブレーク・ポイントを設定する行が指定行から逆方向に検索されます。 |
|
|
このブレーク・ポイントを通知するまでの待機回数。 |
このプロシージャは、タイムアウト発生時のターゲット・セッションの処理方法をプローブに通知します。このコールは、ターゲット・セッションで行われます。
パラメータ
表52-41 SET_TIMEOUT_BEHAVIOURプロシージャのパラメータ
| パラメータ | 説明 |
|---|---|
|
|
|
|
|
再試行します。タイムアウトの効果はありません。timeoutに無限に大きい値を設定した場合と同じです。 |
|
|
同じイベント・フラグを使用して、実行を継続します。 |
|
|
debug-modeをオフにして(つまり、 |
|
|
|
このファンクションは、現在実行中のプログラムに値を設定します。SET_VALUEファンクションは、2種類オーバーロードされています。
構文
DBMS_DEBUG.SET_VALUE ( frame# IN binary_integer, assignment_statement IN varchar2) RETURN BINARY_INTEGER; DBMS_DEBUG.SET_VALUE ( handle IN program_info, assignment_statement IN VARCHAR2) RETURN BINARY_INTEGER;
戻り値
表52-43 SET_VALUEファンクションの戻り値
| 戻り値 | 説明 |
|---|---|
|
|
- |
|
|
指定した値を設定できません。 |
|
|
オブジェクト・タイプは'NOT |
|
|
値がスカラーではありません。 |
|
|
代入文をスカラーに変換できません。たとえば、'x := 3;'(xがレコードの場合)のように指定します。 |
|
|
次のいずれかです。 - パッケージが存在しません。 - パッケージがインスタンス化されていません。 - ユーザーにパッケージをデバッグする権限がありません。 - オブジェクトがパッケージ内に存在しません。 |
現行のブレーク・ポイントのリストを戻すプロシージャは、2種類オーバーロードされています。SHOW_BREAKPOINTSプロシージャは、3種類オーバーロードされています。
このプロシージャは、ソース・コードを取得します。SHOW_SOURCEプロシージャは、2種類オーバーロードされています。
構文
DBMS_DEBUG.SHOW_FRAME_SOURCE ( first_line IN BINARY_INTEGER, last_line IN BINARY_INTEGER, source IN OUT NOCOPY vc2_table, frame_num IN BINARY_INTEGER);
使用上の注意
このファンクションは、任意のフレーム位置で匿名ユニットが実行中であることをバックトレースが示し、ブレーク・ポイントを設定するためにソースを確認する必要があるときのみ使用します。
フレーム番号がスタックの最上部にあり、それが匿名ブロックの場合は、SHOW_SOURCEも使用できます。
フレーム番号が、ストアドPLSQLパッケージ、ファンクションまたはプロシージャの場合は、「SHOW_SOURCEプロシージャ」の「使用上の注意」に示すようにSQLを使用します。
このプロシージャは、ソース・コードを取得します。SHOW_SOURCEプロシージャは、2種類オーバーロードされています。
構文
DBMS_DEBUG.SHOW_SOURCE ( first_line IN BINARY_INTEGER, last_line IN BINARY_INTEGER, source OUT vc2_table); DBMS_DEBUG.SHOW_SOURCE ( first_line IN BINARY_INTEGER, last_line IN BINARY_INTEGER, window IN BINARY_INTEGER, print_arrow IN BINARY_INTEGER, buffer IN OUT VARCHAR2, buflen IN BINARY_INTEGER, pieces OUT BINARY_INTEGER);
パラメータ
表52-46 SHOW_SOURCEプロシージャのパラメータ
| パラメータ | 説明 |
|---|---|
|
|
フェッチする最初の行の行番号(PL/SQLプログラムは、常に行1から始まり、途中の行が抜けることはありません)。 |
|
|
フェッチする最後の行の行番号。プログラムの行数を超えると行はフェッチされません。 |
|
|
結果の表。行番号で索引が設定されている場合があります。 |
|
|
行の'ウィンドウ'(現行のソース行の概数)。 |
|
|
0(ゼロ)以外の場合は、カレント行の前に矢印が出力されます。 |
|
|
ソース・リストを格納するバッファ。 |
|
|
バッファの長さ。 |
|
|
指定したバッファにすべてのソースを格納できない可能性がある場合は、0(ゼロ)以外の値が設定されます。 |
使用上の注意
(実行されているプログラムの)ソース・コードを取得する最適な方法は、SQLを使用することです。次に例を示します。
DECLARE
info DBMS_DEBUG.runtime_info;
BEGIN
-- call DBMS_DEBUG.SYNCHRONIZE, CONTINUE,
-- or GET_RUNTIME_INFO to fill in 'info'
SELECT text INTO <buffer> FROM all_source
WHERE owner = info.Program.Owner
AND name = info.Program.Name
AND line = info.Line#;
END;
ただし、このコードは非永続プログラム(無名ブロックやトリガー起動ブロックなど)では機能しません。非永続プログラムの場合は、SHOW_SOURCEをコールしてください。2通りの方法があり、1つはソース行の索引表を戻し、他の1つはパック(およびフォーマット)されたバッファを戻します。
2番目のSHOW_SOURCEのオーバーロードは、フォーマット済バッファに行番号の付いたソースを戻します。索引表を使用するより高速ですが、すべてのソースがフェッチされるとはかぎりません。
ソースがバッファ長(buflen)にすべて格納できなかった場合は、GET_MORE_SOURCEプロシージャを使用して追加のピースを取り出せます(piecesは、取り出す必要のある追加ピースの数を戻します)。
このファンクションは、ターゲット・プログラムがイベントを通知するまで待機します。info_requestedがNULLでない場合は、GET_RUNTIME_INFOをコールします。
構文
DBMS_DEBUG.SYNCHRONIZE ( run_info OUT runtime_info, info_requested IN BINARY_INTEGER := NULL) RETURN BINARY_INTEGER;
パラメータ
表52-47 SYNCHRONIZEファンクションのパラメータ
| パラメータ | 説明 |
|---|---|
|
|
プログラムに関する情報を書き込むためのデータ構造。デフォルトでは、実行中のプログラムおよび一時停止している行に関する情報が含まれます。 |
|
|
デフォルト( |
