53 DBMS_DEBUG

DBMS_DEBUGの使用は推奨されていません。かわりにDBMS_DEBUG_JDWPを使用してください。

詳細は、「DBMS_DEBUG_JDWP」を参照してください。

DBMS_DEBUGは、OracleサーバーにおけるPL/SQLデバッガ・レイヤー、プローブに対するPL/SQLインタフェースです。

このパッケージは、主にサーバー側のデバッガを実装することを目的としており、サーバー側のPL/SQLプログラム・ユニットをデバッグする方法を提供します。

注意:

プログラム・ユニットという用語は、各種のPL/SQLプログラム(プロシージャ、ファンクション、パッケージ、パッケージ本体、トリガー、無名ブロック、オブジェクト・タイプまたはオブジェクト・タイプ本体)のことを指します。

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

53.1 DBMS_DEBUGの概要

サーバー側のコードをデバッグするには、2つのデータベース・セッションが必要です。1つはコードをデバッグ・モードで実行するセッション(ターゲット・セッション)、他の1つはそのターゲット・セッションを監視するセッション(デバッグ・セッション)です。

ターゲット・セッションは、DBMS_DEBUGで初期化コールを行うことでデバッグ可能になります。これにより、そのセッションにマークが付けられるため、PL/SQLインタプリタがデバッグ・モードで実行され、デバッグ・イベントが生成されます。デバッグ・イベントが生成されると、それらはセッションから転送されます。ほとんどの場合、デバッグ・イベントには戻り通知が必要なため、インタプリタは応答があるまで一時停止します。

この間に、デバッグ・セッション自体はDBMS_DEBUGを使用して初期化する必要があり、これによって、監視するターゲット・セッションが識別されます。次に、デバッグ・セッションはDBMS_DEBUGのエントリ・ポイントをコールして、ターゲット・セッションから転送されたイベントを読み込み、ターゲット・セッションと通信します。

次のサブプログラムは、ターゲット・セッション(デバッグ対象のセッション)で実行されます。

DBMS_DEBUGは、PL/SQLコンパイラへのインタフェースは提供しませんが、コンパイラがオプションで生成するデバッグ情報には依存します。デバッグ情報がないと、パラメータまたは変数の値の検証や変更を実行できません。

53.2 DBMS_DEBUGの定数

ブレーク・ポイント・ステータスは、値がbreakpoint_status_unused (ブレーク・ポイントは使用されていません)である場合があります。

ブレーク・ポイントが使用されている場合、状態は次の値のマスクになります。

  • breakpoint_status_active: 行ブレーク・ポイント。

  • breakpoint_status_disabled: ブレーク・ポイントは現在使用できません。

  • breakpoint_status_remote: shadowブレーク・ポイント(リモート・ブレーク・ポイントのローカル表示)

53.3 DBMS_DEBUGの変数

DBMS_DEBUGでは、次の表に示す変数が使用されます。

表53-1 DBMS_DEBUGの変数

変数 説明

default_timeout

タイムアウトの値(両方のセッションが使用)。タイムアウトの最小許容値は1秒です。この値が0 (ゼロ)に設定された場合は、大きい値(3600)が使用されます。

53.4 DBMS_DEBUGの例外

この値は、デバッグ・セッション(SYNCHRONIZECONTINUESET_BREAKPOINTなど)でコールされる様々なファンクションによって戻されます。PL/SQL例外がクライアント/サーバーおよびサーバー/サーバーの境界を越えて発生した場合は、すべて例外となり、エラー・コードは戻されません。

表53-2 DBMS_DEBUGの例外

ステータス 説明

success

正常終了

GET_VALUEおよびSET_VALUEによって戻されるステータスは次のとおりです。

表53-3 GET_VALUEおよびSET_VALUEが戻すDBMS_DEBUGの例外

ステータス 説明

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によって戻されるステータスは次のとおりです。

表53-4 SET_VALUEが戻すDBMS_DEBUGの例外

ステータス 説明

error_illegal_value

制約違反。

error_illegal_null

制約違反。

error_value_malformed

指定された値を解読できません。

error_other

その他のエラー。

error_name_incomplete

名前をスカラーに変換できません。

ブレーク・ポイント・ファンクションによって戻されるステータスは次のとおりです。

表53-5 ブレーク・ポイント・ファンクションによって戻されるステータス

ステータス 説明

error_no_such_breakpt

該当するブレーク・ポイントがありません。

error_idle_breakpt

未使用のブレーク・ポイントは使用可能または使用禁止にできません。

error_bad_handle

指定されたプログラムにブレーク・ポイントを設定できません(存在していないか、またはセキュリティ違反です)。

一般的なエラー・コード(多数のDBMS_DEBUGサブプログラムが戻す)は次のとおりです。

表53-6 DBMS_DEBUGサブプログラムのエラー・コード

ステータス 説明

error_unimplemented

機能が実装されていません。

error_deferred

プログラムが実行されていません。操作は延期されました。

error_exception

サーバー上のDBMS_DEBUGまたはプローブ・パッケージで例外が発生しました。

error_communication

タイムアウト以外のエラーが発生しました。

error_timeout

タイムアウトが発生しました。

表53-7 illegal_initの例外

例外 説明

illegal_init

INITIALIZEの前にDEBUG_ONがコールされました。

次の例外は、プロシージャSELF_CHECKによって発生します。

表53-8 SELF_CHECKプロシージャの例外

例外 説明

pipe_creation_failure

パイプを作成できませんでした。

pipe_send_failure

パイプにデータを書き込めませんでした。

pipe_receive_failure

パイプからデータを読み込めませんでした。

pipe_datatype_mismatch

パイプ内のデータ・タイプが正しくありませんでした。

pipe_data_error

データがパイプ内で混同されていました。

53.5 DBMS_DEBUGの使用上の注意

デバッグ情報の生成を確認する方法は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;

図53-1および図53-2に、デバッグ対象のセッションおよびデバッグ・セッションでの操作のフローを示します。

図53-1 ターゲット・セッション

図53-1の説明が続きます
「図53-1 対象セッション」の説明

図53-2 デバッグ・セッション

図53-2の説明が続きます
「図53-2 デバッグ・セッション」の説明

図53-3 デバッグ・セッション(続き)

図53-3の説明が続きます
「図53-3 デバッグ・セッション(続き)」の説明

インタプリタの管理

インタプリタは、次の場合に実行を一時停止します。

  1. インタプリタの起動時。実行前に、遅延ブレーク・ポイントをインストールできるようにするため。

  2. 使用可能なブレーク・ポイントを含んだ行に達したとき。

  3. 関連のあるイベントが発生した行に達したとき。関連イベントのセットは、breakflagsパラメータのDBMS_DEBUG.CONTINUEに渡されるフラグで指定します。

セッションの終了

セッション終了のイベントはありません。したがって、ターゲット・セッションが終了していないことを、デバッグ・セッションでチェックして確認する必要があります。ターゲット・セッションが終了した後にDBMS_DEBUG.SYNCHRONIZEをコールすると、タイムアウトするまでデバッグ・セッションがハングアップします。

遅延操作

図では、ターゲット・セッションの前にブレーク・ポイントを設定できることが示されています。これは確かに可能です。この場合、プローブはブレーク・ポイント要求をキャッシュして、最初の同期でターゲット・セッションに送信します。ただし、ブレーク・ポイント要求がこのように遅延した場合は次のようになります。

  • SET_BREAKPOINTはブレーク・ポイント番号を設定しません(必要に応じて後でSHOW_BREAKPOINTSから取得できます)。

  • SET_BREAKPOINTはブレーク・ポイント要求を検証しません。要求されたソース行が存在しない場合は、同期時にエラーが内部的に発生し、ブレーク・ポイントは設定されません。

診断出力

プローブをデバッグするために、DBMS_DEBUGのコールの一部に対してdiagnosticsパラメータが用意されています。これらのパラメータは、RDBMSトレース・ファイルに診断出力を格納するかどうかを指定します。RDBMSトレース・ファイルに出力できない場合、このパラメータは無効になります。

共通セクションおよびデバッグ・セッション・セクション

  • 共通セクション

  • ターゲット・セッション

  • デバッグ・セッション・セクション

共通セクション

次に示すサブプログラムは、ターゲットまたはデバッグ・セッションのいずれでもコールできます。

ターゲット・セッション

次のサブプログラムは、ターゲット・セッションでのみコールできます。

デバッグ・セッション・セクション

次のサブプログラムは、デバッグ・セッションでのみ実行してください。

OERブレーク・ポイント

PL/SQLプログラム内で宣言される例外は、ユーザー定義の例外として認識されています。さらに、Oracleカーネルから戻されるOracleエラー(OER)があります。この2つのメカニズムを結合するために、PL/SQLはユーザー定義の例外をOERに変換するexception_initプラグマを提供していて、この処理にはPL/SQLハンドラが使用され、PL/SQLエンジンは、OERをOracleカーネルに戻すことができます。現行のリリースでは、OERに関する使用可能な情報はその番号のみです。2つのユーザー定義例外が同じOERにexception_initされると、区別できません。

ネームスペース

サーバー上のプログラム・ユニットは、異なるネームスペースに常駐しています。ブレーク・ポイントの設定時には、希望するネームスペースを指定してください。

  1. Namespace_cursorにはカーソル(無名ブロック)が含まれています。

  2. Namespace_pgkspec_or_toplevelには次が含まれています。

    • パッケージの仕様部。

    • 他のパッケージ、プロシージャまたはファンクション内にネストされていないプロシージャおよびファンクション

    • オブジェクト・タイプ。

  3. Namespace_pkg_bodyにはパッケージ本体およびタイプ本体が含まれています。

  4. Namespace_triggerにはトリガーが含まれています。

Libunitタイプ

この値は、特定のネームスペースのオブジェクトを一意化するために使用されます。これらの定数は、プローブがスタックのバックトレースを提供しているときに、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_returnProc2の終了時に停止します。)

break_exception

例外が発生したときにブレークします。

break_handler

例外ハンドラが実行されたときにブレークします。

abort_execution

実行を停止し、DBMS_DEBUG.CONTINUEがコールされるとすぐに、'exit'イベントを強制的に実行します。

情報フラグ

このフラグは、info_requestedパラメータとしてSYNCHRONIZECONTINUEおよび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

インタプリタは異常終了中です。

53.6 DBMS_DEBUGのデータ構造

DBMS_DEBUGパッケージでは、レコード・タイプおよびタイプを定義します。

53.6.1 BREAKPOINT_INFOレコード・タイプ

このタイプは、ブレーク・ポイントに関して、現在の状態や配置されたプログラム・ユニットなどの情報を提供します。

構文

TYPE breakpoint_info IS RECORD (
   name        VARCHAR2(30),
   owner       VARCHAR2(30),
   dblink      VARCHAR2(30),
   line#       BINARY_INTEGER,
   libunittype BINARY_INTEGER,
   status      BINARY_INTEGER);

フィールド

表53-9 BREAKPOINT_INFOフィールド

フィールド 説明

name

プログラム・ユニットの名前。

owner

プログラム・ユニットの所有者。

dblink

データベース・リンク(リモートの場合)。

line#

行番号。

libunittype

ネストされたプロシージャまたはファンクション以外はNULLです。

status

breakpoint_status_*の値については、「定数」を参照してください。

53.6.2 PROGRAM_INFOレコード・タイプ

DBMS_DEBGパッケージのPROGRAM_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));

フィールド

表53-10 PROGRAM_INFOのフィールド

フィールド 説明

namespace

ネームスペースの詳細は、「DBMS_DEBUGの使用上の注意」を参照してください。

name

プログラム・ユニットの名前。

owner

プログラム・ユニットの所有者。

dblink

データベース・リンク(リモートの場合)。

line#

行番号。

libunittype

読取り専用フィールド。ネストされたプロシージャまたはファンクション以外はNULLです。

entrypointname

読取り専用フィールド。同じネームスペースを共有するオブジェクト(プロシージャやパッケージ仕様部など)を一意化します。

libunitタイプの詳細は、「DBMS_DEBUGの使用上の注意」を参照してください。

53.6.3 RUNTIME_INFOレコード・タイプ

このタイプは、実行プログラムに関するコンテキスト情報を提供します。

構文

TYPE runtime_info IS RECORD(
    line#            BINARY_INTEGER,
    terminated       binary_integer,
    breakpoint       binary_integer,
    stackdepth       BINARY_INTEGER,
    interpreterdepth BINARY_INTEGER,
    reason           BINARY_INTEGER, 
    program          program_info);

フィールド

表53-11 RUNTIME_INFOのフィールド

フィールド 説明

line#

program.line#の複製

terminated

プログラムが終了しているかどうか

breakpoint

ブレーク・ポイント番号

stackdepth

スタック上のフレームの数

interpreterdepth

[予約フィールド]

reason

中断理由

program

ソースの場所

53.6.4 BACKTRACE_TABLE表タイプ

このタイプは、PRINT_BACKTRACEで使用されます。

構文

TYPE backtrace_table IS TABLE OF program_info INDEX BY BINARY_INTEGER;

53.6.5 BREAKPOINT_TABLE表タイプ

このタイプは、SHOW_BREAKPOINTSで使用されます。

構文

TYPE breakpoint_table IS TABLE OF breakpoint_info INDEX BY BINARY_INTEGER;

53.6.6 INDEX_TABLE表タイプ

このタイプは、索引表で使用可能な索引を戻すために、GET_INDEXESで使用されます。

構文

TYPE index_table IS table of BINARY_INTEGER INDEX BY BINARY_INTEGER;

53.6.7 VC2_TABLE表タイプ

このタイプは、SHOW_SOURCEで使用されます。

構文

TYPE vc2_table IS TABLE OF VARCHAR2(90) INDEX BY BINARY_INTEGER;

53.7 DBMS_DEBUGサブプログラムの要約

この表は、DBMS_DEBUGサブプログラムをアルファベット順に示し、簡単に説明しています。

表53-12 DBMS_DEBUGパッケージのサブプログラム

サブプログラム 説明

ATTACH_SESSIONプロシージャ

デバッグ・セッションにターゲット・デバッグIDに関する情報を通知します。

CONTINUEファンクション

ターゲット・プログラムの実行を継続します。

DEBUG_OFFプロシージャ

デバッグ・モードをオフにします。

DEBUG_ONプロシージャ

デバッグ・モードをオンにします。

DELETE_BREAKPOINTファンクション

ブレーク・ポイントを削除します。

DELETE_OER_BREAKPOINTファンクション

OERブレーク・ポイントを削除します。

DETACH_SESSIONプロシージャ

ターゲット・プログラムのデバッグを停止します。

DISABLE_BREAKPOINTファンクション

ブレーク・ポイントを無効にします。

ENABLE_BREAKPOINTファンクション

既存のブレーク・ポイントをアクティブにします。

EXECUTEプロシージャ

ターゲット・セッションでSQLまたはPL/SQLを実行します。

GET_INDEXESファンクション

索引表に対する一連の索引を戻します。

GET_MORE_SOURCEプロシージャ

SHOW_SOURCEの使用時に、バッファ・オーバーフローが起きたときに追加ソースを提供します。

GET_LINE_MAPファンクション

プログラム・ユニット内の行番号に関する情報を戻します。

GET_RUNTIME_INFOファンクション

現行のプログラムに関する情報を戻します。

GET_TIMEOUT_BEHAVIOURファンクション

現行のタイムアウト動作を戻します。

GET_VALUEファンクション

現在実行中のプログラムから値を取得します。

INITIALIZEファンクション

ターゲット・セッションのデバッグIDを設定します。

PINGプロシージャ

ターゲット・セッションがタイムアウトしないようにpingします。

PRINT_BACKTRACEプロシージャ

スタックのバックトレースを印刷します。

PRINT_INSTANTIATIONSプロシージャ

スタックのバックトレースを印刷します。

PROBE_VERSIONプロシージャ

サーバー上のDBMS_DEBUGのバージョン番号を戻します。

SELF_CHECKプロシージャ

内部一貫性チェックを実行します。

SET_BREAKPOINTファンクション

プログラム・ユニットにブレーク・ポイントを設定します。

SET_OER_BREAKPOINTファンクション

OERブレーク・ポイントを設定します。

SET_TIMEOUTファンクション

タイムアウト値を設定します。

SET_TIMEOUT_BEHAVIOURプロシージャ

タイムアウトの発生時に、ターゲット・セッションに行う処理をプローブに指示します。

SET_VALUEファンクション

現在実行中のプログラムに値を設定します。

SHOW_BREAKPOINTSプロシージャ

現行のブレーク・ポイントのリストを戻します。

SHOW_FRAME_SOURCEプロシージャ

フレーム・ソースをフェッチします。

SHOW_SOURCEプロシージャ

プログラム・ソースをフェッチします。

SYNCHRONIZEファンクション

プログラムの実行開始を待機します。

TARGET_PROGRAM_RUNNINGプロシージャ

ターゲット・セッションが現在ストアド・プロシージャを実行中の場合はTRUE、実行していない場合はFALSEを戻します。

53.7.1 ATTACH_SESSIONプロシージャ

このプロシージャは、ターゲット・プログラムに関する情報をデバッグ・セッションに通知します。

構文

DBMS_DEBUG.ATTACH_SESSION (
   debug_session_id  IN VARCHAR2,
   diagnostics       IN BINARY_INTEGER := 0); 

パラメータ

表53-13 ATTACH_SESSIONプロシージャのパラメータ

パラメータ 説明

debug_session_id

ターゲット・セッションのINITIALIZEコールで取得したデバッグID。

diagnostics

0(ゼロ)以外の場合に診断出力を生成します。

53.7.2 CONTINUEファンクション

このファンクションは、指定されたブレーク・フラグ(関連のあるイベントのマスク)をターゲット・プロセスのプローブに渡します。プローブに、ターゲット・プロセスの実行を継続するように通知し、ターゲット・プロセスが実行を終了するか、またはイベントを通知するまで待機します。

info_requestedNULLでない場合は、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;

パラメータ

表53-14 CONTINUEファンクションのパラメータ

パラメータ 説明

run_info

プログラムの状態に関する情報。

breakflags

対象となるイベントのマスク(「DBMS_DEBUGの使用上の注意」のブレーク・フラグの説明を参照)。

info_requested

プログラムが停止したときに、run_infoに戻される必要のある情報(「DBMS_DEBUGの使用上の注意」の情報フラグの説明を参照)。

戻り値

表53-15 CONTINUEファンクションの戻り値

戻り値 説明

success

error_timeout

プログラムが実行を開始する前にタイムアウトしました。

error_communication

その他の通信エラー。

53.7.3 DEBUG_OFFプロシージャ

このプロシージャは、そのセッションでデバッグを実行する必要がなくなったことをターゲット・セッションに通知します。セッションの終了前にこのファンクションをコールする必要はありません。

警告:

immediateがTRUEの場合、デバッグ・セッションは待機する必要があります。

構文

DBMS_DEBUG.DEBUG_OFF;

使用上の注意

サーバーは、このエントリポイントを特別には処理しません。したがって、このエントリポイントをデバッグしようとします。

53.7.4 DEBUG_ONプロシージャ

このプロシージャは、すべてのPL/SQLがデバッグ・モードで実行されるように、ターゲット・セッションにマークを設定します。この処理は、デバッグの開始前に実行する必要があります。

構文

DBMS_DEBUG.DEBUG_ON (
   no_client_side_plsql_engine BOOLEAN := TRUE,
   immediate                   BOOLEAN := FALSE); 

パラメータ

表53-16 DEBUG_ONプロシージャのパラメータ

パラメータ 説明

no_client_side_plsql_engine

デバッグ・セッションがクライアント側のPL/SQLエンジンから起動されていないかぎり、デフォルト値のままにしてください。

immediate

TRUEの場合、インタプリタは標準モードで処理を継続せずに、コール中にすぐにデバッグ・モードに切り替わります。

53.7.5 DELETE_BREAKPOINTファンクション

このファンクションはブレーク・ポイントを削除します。

構文

DBMS_DEBUG.DELETE_BREAKPOINT (
   breakpoint IN BINARY_INTEGER)
  RETURN BINARY_INTEGER;

パラメータ

表53-17 DELETE_BREAKPOINTファンクションのパラメータ

パラメータ 説明

breakpoint

以前のSET_BREAKPOINTコールから戻されたブレーク・ポイント番号。

戻り値

表53-18 DELETE_BREAKPOINTファンクションの戻り値

戻り値 説明

success

error_no_such_breakpt

該当するブレーク・ポイントが存在しません。

error_idle_breakpt

未使用のブレーク・ポイントは削除できません。

error_stale_breakpt

ブレーク・ポイントが設定された後にプログラム・ユニットが再定義されました。

53.7.6 DELETE_OER_BREAKPOINTファンクション

このファンクションは、OERブレーク・ポイントを削除します。

構文

DBMS_DEBUG.DELETE_OER_BREAKPOINT (
   oer  IN PLS_INTEGER) 
RETURN PLS_INTEGER; 

パラメータ

表53-19 DELETE_OER_BREAKPOINTファンクションのパラメータ

パラメータ 説明

oer

削除するOER(4バイトの正数)。

53.7.7 DETACH_SESSIONプロシージャ

このプロシージャは、ターゲット・プログラムのデバッグを停止します。

このプロシージャはいつでもコール可能ですが、デバッグ・セッションの連結が解除されたことはターゲット・セッションに通知されず、ターゲット・セッションの実行は終了しません。したがって、ターゲット・セッションが独自にハングアップしないように注意してください。

構文

DBMS_DEBUG.DETACH_SESSION;  

53.7.8 DISABLE_BREAKPOINTファンクション

このファンクションは、既存のブレーク・ポイントを使用禁止にしますが、削除しないでそのまま残します。

構文

DBMS_DEBUG.DISABLE_BREAKPOINT (
   breakpoint IN BINARY_INTEGER)
  RETURN BINARY_INTEGER; 

パラメータ

表53-20 DISABLE_BREAKPOINTファンクションのパラメータ

パラメータ 説明

breakpoint

以前のSET_BREAKPOINTコールから戻されたブレーク・ポイント番号。

戻り値

表53-21 DISABLE_BREAKPOINTファンクションの戻り値

戻り値 説明

success

error_no_such_breakpt

該当するブレーク・ポイントが存在しません。

error_idle_breakpt

未使用のブレーク・ポイントは使用禁止にできません。

53.7.9 ENABLE_BREAKPOINTファンクション

このファンクションは、使用禁止の逆の処理を実行します。以前に使用禁止にしたブレーク・ポイントを使用可能にします。

構文

DBMS_DEBUG.ENABLE_BREAKPOINT (
   breakpoint IN BINARY_INTEGER)
  RETURN BINARY_INTEGER;

パラメータ

表53-22 ENABLE_BREAKPOINTファンクションのパラメータ

パラメータ 説明

breakpoint

以前のSET_BREAKPOINTコールから戻されたブレーク・ポイント番号。

戻り値

表53-23 ENABLE_BREAKPOINTファンクションの戻り値

戻り値 説明

success

成功。

error_no_such_breakpt

該当するブレーク・ポイントが存在しません。

error_idle_breakpt

未使用のブレーク・ポイントは使用可能にできません。

53.7.10 EXECUTEプロシージャ

このプロシージャは、ターゲット・セッションで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);

パラメータ

表53-24 EXECUTEプロシージャのパラメータ

パラメータ 説明

what

実行するSQLまたはPL/SQLのソース。

frame#

コードを実行するコンテキスト。現在は-1(グローバル・コンテキスト)のみサポートされています。

bind_results

ターゲット・セッションから値を戻すために、ソースをresultsに結合するかどうかを指定します。

0 = いいえ

1 = はい

results

結果を格納するコレクション(bind_resultsが0(ゼロ)以外の場合)。

errm

エラーが発生した場合はエラー・メッセージ、それ以外の場合はNULLです。

例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;

53.7.11 GET_INDEXESファンクション

変数またはパラメータの名前を指定すると、索引表の場合はその一連の索引を戻します。索引表以外の場合はエラーが戻されます。

構文

DBMS_DEBUG.GET_INDEXES (
   varname   IN  VARCHAR2,
   frame#    IN  BINARY_INTEGER,
   handle    IN  program_info,
   entries   OUT index_table) 
RETURN BINARY_INTEGER;

パラメータ

表53-25 GET_INDEXESファンクションのパラメータ

パラメータ 説明

varname

索引情報を取得する変数の名前。

frame#

変数またはパラメータが常駐しているフレームの番号。パッケージ変数の場合はNULLです。

handle

パッケージの説明(オブジェクトがパッケージ変数の場合)。

entries

1ベースの索引表: NULL以外の場合は、entries(1)にその行の1番目の索引、entries(2)に2番目の索引が含まれ、以降同様に索引が含まれます。

戻り値

表53-26 GET_INDEXESファンクションの戻り値

戻り値 説明

error_no_such_object

次のうちの1つ。

- パッケージが存在しません。

- パッケージがインスタンス化されていません。

- ユーザーにパッケージをデバッグする権限がありません。

- オブジェクトがパッケージ内に存在しません。

53.7.12 GET_MORE_SOURCEプロシージャ

フォーマット済バッファを生成したSHOW_SOURCEプロシージャの該当バージョンによって提供されたバッファにソースが収まらない場合、このプロシージャが追加ソースを提供します。

構文

DBMS_DEBUG.GET_MORE_SOURCE (
   buffer          IN OUT VARCHAR2,
   buflen          IN BINARY_INTEGER,
   piece#          IN BINARY_INTEGER);

パラメータ

表53-27 GET_MORE_SOURCEプロシージャのパラメータ

パラメータ 説明

buffer

バッファ

buflen

バッファの長さ。

piece#

2とSHOW_SOURCEプロシージャの適切なバージョンへのコールからパラメータの各部分に戻された値との間の値

使用上の注意

このプロシージャは、フォーマット済バッファを戻すSHOW_SOURCEの該当バージョンの後にのみコールします。

53.7.13 GET_LINE_MAPファンクション

このファンクションは、ブレーク・ポイントを配置できるソース行をデバッガが決定できるように、プログラムに関する行およびエントリポイントの情報を検索します。

構文

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; 

パラメータ

表53-28 GET_LINE_MAPファンクションのパラメータ

パラメータ 説明

program

トップレベルのプログラム・ユニット(プロシージャ、パッケージ、ファンクション、パッケージ本体など)。NamespaceNameおよびOwnerの各フィールドは初期化する必要がありますが、残りのフィールドは無視されます。

maxline

'program'内で最大のソース・コード行番号。

number_of_entry_points

'program'内のサブプログラムの数。

linemap

'program'の実行可能行を表すビットマップ。行番号Nが実行可能である場合、ビット番号N MOD 8がラインマップ位置N / 8で1に設定されます。戻されるラインマップの長さは、maxlineを8で割ったものか(maxline MOD 8が0(ゼロ)以外の場合は1を加算)、または、ほとんど発生しないケースですが、maxlineが32767 * 8よりも大きい場合は32767のいずれかになります。

戻り値

表53-29 GET_LINE_MAPファンクションの戻り値

戻り値 説明

success

正常な完了。

error_no_debug_info

プログラム・ユニットは存在しますが、デバッグ情報がありません。

error_bad_handle

該当するプログラム・ユニットが存在しません。

53.7.14 GET_RUNTIME_INFOファンクション

このファンクションは、現行のプログラムに関する情報を戻します。これは、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; 

パラメータ

表53-30 GET_RUNTIME_INFOファンクションのパラメータ

パラメータ 説明

info_requested

プログラムが停止したときに、run_infoに戻される必要のある情報(情報フラグの詳細は、「DBMS_DEBUGの使用上の注意」を参照)。

run_info

プログラムの状態に関する情報。

53.7.15 GET_TIMEOUT_BEHAVIOURファンクション

このプロシージャは、現行のタイムアウト動作を戻します。このコールは、ターゲット・セッションで行われます。

構文

DBMS_DEBUG.GET_TIMEOUT_BEHAVIOUR
 RETURN BINARY_INTEGER; 

パラメータ

表53-31 GET_TIMEOUT_BEHAVIOURファンクションのパラメータ

パラメータ 説明

oer

OER(4バイトの正数)

戻り値

表53-32 GET_TIMEOUT_BEHAVIOURファンクションの戻り値

戻り値 説明

success

正常な完了。

情報フラグ

info_getOerInfo CONSTANT PLS_INTEGER:= 32; 

使用上の注意

OERブレーク・ポイントでサポートされている機能は、コード・ブレーク・ポイントと比較すると少なくなります。特に、次の点に注意してください。

  • ブレーク・ポイント番号は戻されず、かわりにOERの番号が使用されます。したがって、指定したOERに複数のブレーク・ポイントは設定できません(操作できません)。

  • OERブレーク・ポイントは使用禁止にできません(ただし、クライアントは、これを削除して自由にシミュレートできます)。

  • OERブレーク・ポイントは、delete_oer_breakpointを使用して削除されます。

53.7.16 GET_VALUEファンクション

このファンクションは、現在実行中のプログラムから値を取得します。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;

パラメータ

表53-33 GET_VALUEファンクションのパラメータ

パラメータ 説明

variable_name

変数またはパラメータの名前。

frame#

値が存在するフレーム。0(ゼロ)の場合は現行のプロシージャです。

scalar_value

format

使用するオプションの日付書式(指定する必要がある場合)。

戻り値

表53-34 GET_VALUEファンクションの戻り値

戻り値 説明

success

正常な完了。

error_bogus_frame

フレームが存在しません。

error_no_debug_info

エントリポイントにデバッグ情報がありません。

error_no_such_object

variable_nameframe#に存在しません。

error_unknown_type

デバッグ情報内のタイプ情報が判読不能です。

error_nullvalue

値はNULL

error_indexed_table

オブジェクトは表ですが、索引が提供されていません。

次の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;

パラメータ

表53-35 GET_VALUEファンクションのパラメータ

パラメータ 説明

variable_name

変数またはパラメータの名前。

handle

変数を含んだパッケージの説明。

scalar_value

format

使用するオプションの日付書式(指定する必要がある場合)。

戻り値

表53-36 GET_VALUEファンクションの戻り値

戻り値 説明

error_no_such_object

次のうちの1つ。

- パッケージが存在しません。

- パッケージがインスタンス化されていません。

- ユーザーにパッケージをデバッグする権限がありません。

- オブジェクトがパッケージ内に存在しません。

error_indexed_table

オブジェクトは表ですが、索引が提供されていません。

この例は、スキーマ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;

53.7.17 INITIALIZEファンクション

このファンクションは、デバッグ用にターゲット・セッションを初期化します。

構文

DBMS_DEBUG.INITIALIZE (
   debug_session_id  IN VARCHAR2       := NULL, 
   diagnostics       IN BINARY_INTEGER := 0)
  RETURN VARCHAR2; 

パラメータ

表53-37 INITIALIZEファンクションのパラメータ

パラメータ 説明

debug_session_id

セッションIDの名前。NULLの場合は、一意のIDが生成されます。

diagnostics

診断出力をトレース・ファイルにダンプするかどうかを示します。

0 = (デフォルト)診断出力なし。

1 = 診断出力あり。

戻り値

新たに登録されたデバッグ・セッションID(デバッグID)

使用上の注意

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権限を検索するチェックは、セッションのログイン・ユーザー、このコールが行われた瞬間のセッション・レベルで使用可能になったロール(そのロールがコールの定義者権限環境内で使用できない場合でも同様)およびデバッグ・ロールのコンテキストで行われます。

53.7.18 PINGプロシージャ

このプロシージャは、ターゲット・セッションがタイムアウトしないようにpingします。ターゲット・セッションで実行が中断したとき、ブレーク・ポイントなどでこのプロシージャを使用します。

timeout_behaviourretry_on_timeoutに設定されている場合、このプロシージャは不要です。

構文

DBMS_DEBUG.PING; 

例外

ターゲット・プログラムがない場合、またはターゲット・セッションがデバッグ・セッションからの入力を待機していない場合は、no_target_program例外が表示されます。

使用上の注意

ターゲット・セッションのタイムアウト・オプションは、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;

53.7.19 PRINT_BACKTRACEプロシージャ

このプロシージャは、現在の実行スタックのバックトレース・リストを出力します。これは、プログラムが実行中の場合のみコールしてください。

PRINT_BACKTRACEプロシージャは、2種類オーバーロードされています。

構文

DBMS_DEBUG.PRINT_BACKTRACE (
  listing IN OUT VARCHAR2); 

DBMS_DEBUG.PRINT_BACKTRACE (
  backtrace OUT backtrace_table);

パラメータ

表53-38 PRINT_BACKTRACEプロシージャのパラメータ

パラメータ 説明

listing

埋込み改行付きのフォーマット済文字バッファ。

backtrace

バックトレース・エントリ1ベースの索引表。現在実行中のプロシージャは、表の最終エントリです(つまり、フレーム番号は、GET_VALUEが使用しているものと同一です)。エントリ1は、スタック上で最も古いプロシージャです。

53.7.20 PRINT_INSTANTIATIONSプロシージャ

このプロシージャは、現行のセッションでインスタンス化されたパッケージのリストを戻します。

構文

DBMS_DEBUG.PRINT_INSTANTIATIONS (
   pkgs   IN OUT NOCOPY backtrace_table, 
   flags  IN BINARY_INTEGER); 

パラメータ

表53-39 PRINT_INSTANTIATIONSプロシージャのパラメータ

パラメータ 説明

pkgs

インスタンス化されたパッケージ

flags

オプションのビットマスク:

  • 1 - 仕様部の表示。

  • 2 - 本体の表示。

  • 4 - ローカル・インスタンス化の表示。

  • 8 - リモート・インスタンス化の表示(NYI)。

  • 16 - 高速ジョブの実行。デバッグ情報が存在しているか、またはライブラリ・ユニットがシュリンクラップされているかどうかはテストされません。

例外

no_target_program: ターゲット・セッションは現在実行されていません。

使用上の注意

pkgsの戻り値には、各インスタンス化されたパッケージのprogram_infoが含まれます。有効なフィールドは、Namespace、Name、OwnerおよびLibunitType です。

また、Line#には次のビットマスクが含まれます。

  • 1 - ライブラリ・ユニットにデバッグ情報が含まれています。

  • 2 - ライブラリ・ユニットはシュリンクラップされています。

53.7.21 PROBE_VERSIONプロシージャ

このプロシージャは、サーバー上のDBMS_DEBUGのバージョン番号を戻します。

構文

DBMS_DEBUG.PROBE_VERSION (
   major out BINARY_INTEGER,
   minor out BINARY_INTEGER); 

パラメータ

表53-40 PROBE_VERSIONプロシージャのパラメータ

パラメータ 説明

major

バージョン番号。

minor

リリース番号: 機能が追加されるたびに増加します。

53.7.22 SELF_CHECKプロシージャ

このプロシージャは、内部一貫性チェックを実行します。SELF_CHECKは、プローブ・プロセスが通信可能かどうかを確認するために、通信テストも実行します。

SELF_CHECKが正常に終了しなかった場合は、このサーバーにインストールされているDBMS_DEBUGのバージョンが適切ではない可能性があります。解決方法は、正しいバージョンをインストールすることです(pbload.sqlを実行すると、DBMS_DEBUGおよびその他の関連パッケージがロードされます)。

構文

DBMS_DEBUG.SELF_CHECK (
   timeout IN binary_integer := 60);

パラメータ

表53-41 SELF_CHECKプロシージャのパラメータ

パラメータ 説明

timeout

通信テストに使用するタイムアウト時間。デフォルトは60秒です。

例外

表53-42 SELF_CHECKプロシージャの例外

例外 説明

OER-6516

プローブのバージョンに一貫性がありません。

pipe_creation_failure

パイプを作成できませんでした。

pipe_send_failure

パイプにデータを書き込めませんでした。

pipe_receive_failure

パイプからデータを読み込めませんでした。

pipe_datatype_mismatch

パイプ内のデータ・タイプが正しくありませんでした。

pipe_data_error

データがパイプ内で混同されていました。

これらはすべて致命的な例外です。プローブの正常な実行を妨げる重大な問題であることを示しています。

53.7.23 SET_BREAKPOINTファンクション

このファンクションは、現行セッションを持続するためのブレーク・ポイントをプログラム・ユニットに設定します。

構文

ターゲット・プログラムがブレーク・ポイントに到達すると、実行は一時停止します。

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;

パラメータ

表53-43 SET_BREAKPOINTファンクションのパラメータ

パラメータ 説明

program

ブレーク・ポイントが設定されるプログラム・ユニットに関する情報。(バージョン2.1以上では、ネームスペース、名前、所有者およびdblinkをNULLに設定でき、この場合のブレーク・ポイントは、現在実行中のプログラム・ユニットに設定されます。)

line#

ブレーク・ポイントが設定される行。

breakpoint#

正常に完了すると、ブレーク・ポイントを参照するための一意のブレーク・ポイント番号が含まれます。

fuzzy

指定した行に実行可能コードがない場合にのみ適用されます。

0(ゼロ)の場合は、error_illegal_lineが戻されます。

1の場合は、ブレーク・ポイントを設定する行が指定行から順方向に検索されます。

-1の場合は、ブレーク・ポイントを設定する行が指定行から逆方向に検索されます。

iterations

このブレーク・ポイントを通知するまでの待機回数。

戻り値

注意:

fuzzyおよびiterationsパラメータは、まだ実装されていません。

表53-44 SET_BREAKPOINTファンクションの戻り値

戻り値 説明

success

正常な完了。

error_illegal_line

この行にブレーク・ポイントは設定できません。

error_bad_handle

該当するプログラム・ユニットが存在しません。

53.7.24 SET_OER_BREAKPOINTファンクション

このファンクションは、OERブレーク・ポイントを設定します。

構文

DBMS_DEBUG.SET_OER_BREAKPOINT (
   oer  IN PLS_INTEGER) 
RETURN PLS_INTEGER; 

パラメータ

表53-45 SET_OER_BREAKPOINTファンクションのパラメータ

パラメータ 説明

oer

設定するOER(4バイトの正数)。

戻り値

表53-46 SET_OER_BREAKPOINTファンクションの戻り値

戻り値 説明

success

正常な完了。

error_no_such_breakpt

該当するブレーク・ポイントが存在しません。

53.7.25 SET_TIMEOUTファンクション

このファンクションは、タイムアウト値を設定し、新しいタイムアウト値を戻します。

構文

DBMS_DEBUG.SET_TIMEOUT (
   timeout BINARY_INTEGER) 
  RETURN BINARY_INTEGER;

パラメータ

表53-47 SET_TIMEOUTファンクションのパラメータ

パラメータ 説明

timeout

ターゲットとデバッグ・セッション間の通信に使用されるタイムアウト

53.7.26 SET_TIMEOUT_BEHAVIOURプロシージャ

このプロシージャは、タイムアウト発生時のターゲット・セッションの処理方法をプローブに通知します。このコールは、ターゲット・セッションで行われます。

構文

DBMS_DEBUG.SET_TIMEOUT_BEHAVIOUR (
   behaviour IN PLS_INTEGER); 

パラメータ

表53-48 SET_TIMEOUT_BEHAVIOURプロシージャのパラメータ

パラメータ 説明

behaviour: 次のいずれかです。

retry_on_timeout

再試行します。タイムアウトの効果はありません。timeoutに無限に大きい値を設定した場合と同じです。

continue_on_timeout

同じイベント・フラグを使用して、実行を継続します。

nodebug_on_timeout

debug-modeをオフにして(つまり、debug_offをコール)、実行を継続します。debug_onをコールして初期化しなおさないかぎり、これ以降、このターゲット・セッションでイベントは生成されません。

abort_on_timeout

abort_executionフラグを使用して実行を継続しますが、これにより、プログラムは即時に終了します。セッションはデバッグ・モードのままです。

例外

unimplemented: 要求された動作が認識されていません。

使用上の注意

デフォルトの動作(このプロシージャがコールされない場合)は、continue_on_timeoutです。これは、デバッガ・クライアントが(次のイベントで)制御を再確立でき、ターゲット・セッションが無期限にハングアップすることはないためです。

53.7.27 SET_VALUEファンクション

このファンクションは、現在実行中のプログラムに値を設定します。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;  

パラメータ

表53-49 SET_VALUEファンクションのパラメータ

パラメータ 説明

frame#

値を設定するフレーム。0(ゼロ)は現在実行中のフレームを意味します。

handle

変数を含んだパッケージの説明。

assignment_statement

値を設定するために実行する代入文(有効なPL/SQLである必要があります)。たとえば、x := 3;のように指定します。

このリリースでは、スカラー値のみサポートされています。代入文の右辺はスカラーである必要があります。

戻り値

表53-50 SET_VALUEファンクションの戻り値

戻り値 説明

success

-

error_illegal_value

指定した値を設定できません。

error_illegal_null

オブジェクト・タイプは'NOT NULL'で指定されているため、NULLは設定できません。

error_value_malformed

値がスカラーではありません。

error_name_incomplete

代入文をスカラーに変換できません。たとえば、'x := 3;'(xがレコードの場合)のように指定します。

error_no_such_object

次のうちの1つ。

- パッケージが存在しません。

- パッケージがインスタンス化されていません。

- ユーザーにパッケージをデバッグする権限がありません。

- オブジェクトがパッケージ内に存在しません。

使用上の注意

PL/SQLコンパイラが一時ファイルを使用してパッケージ変数にアクセスし、このような一時ファイルの更新を保証しない場合があります。ほとんど発生しませんが、SET_VALUEを使用したパッケージ変数の変更が反映されない行があります。

SCOTT.PACK.varの値を6に設定する方法は次のとおりです。

DECLARE
   handle  dbms_debug.program_info;
   retval  BINARY_INTEGER;
BEGIN
   handle.Owner     := 'SCOTT';
   handle.Name      := 'PACK';
   handle.namespace := dbms_debug.namespace_pkgspec_or_toplevel;
   retval           := dbms_debug.set_value(handle, 'var := 6;');
END;

53.7.28 SHOW_BREAKPOINTSプロシージャ

現行のブレーク・ポイントのリストを戻すプロシージャは、2種類オーバーロードされています。SHOW_BREAKPOINTSプロシージャは、3種類オーバーロードされています。

構文

DBMS_DEBUG.SHOW_BREAKPOINTS (
   listing    IN OUT VARCHAR2);

DBMS_DEBUG.SHOW_BREAKPOINTS (
   listing    OUT breakpoint_table);

DBMS_DEBUG.SHOW_BREAKPOINTS (
   code_breakpoints  OUT breakpoint_table, 
   oer_breakpoints   OUT oer_table);

パラメータ

表53-51 SHOW_BREAKPOINTSプロシージャのパラメータ

パラメータ 説明

listing

ブレーク・ポイントのフォーマット済バッファ(改行を含む)。

ブレーク・ポイント・エントリの索引表。ブレーク・ポイント番号は、表に対する索引で示されます。ブレーク・ポイント番号は1から始まり、削除されると再使用されます。

code_breakpoints

ブレーク・ポイント番号で索引付けされた、ブレーク・ポイント・エントリの索引表。

oer_breakpoints

OERで索引付けされた、OERブレーク・ポイントの索引表。

53.7.29 SHOW_FRAME_SOURCEプロシージャ

このプロシージャは、ソース・コードを取得します。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);

パラメータ

表53-52 SHOW_FRAME_SOURCEプロシージャのパラメータ

パラメータ 説明

first_line

フェッチする最初の行の行番号(PL/SQLプログラムは、常に行1から始まり、途中の行が抜けることはありません)。

last_line

フェッチする最後の行の行番号。プログラムの行数を超えると行はフェッチされません。

source

結果の表。行番号で索引が設定されている場合があります。

frame_num

1から開始するフレーム番号。

使用上の注意

  • このファンクションは、任意のフレーム位置で匿名ユニットが実行中であることをバックトレースが示し、ブレーク・ポイントを設定するためにソースを確認する必要があるときのみ使用します。

  • フレーム番号がスタックの最上部にあり、それが匿名ブロックの場合は、SHOW_SOURCEも使用できます。

  • フレーム番号が、ストアドPL/SQLパッケージ、ファンクションまたはプロシージャの場合は、「SHOW_SOURCEプロシージャ」「使用上の注意」に示すようにSQLを使用します。

53.7.30 SHOW_SOURCEプロシージャ

このプロシージャは、ソース・コードを取得します。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);  

パラメータ

表53-53 SHOW_SOURCEプロシージャのパラメータ

パラメータ 説明

first_line

フェッチする最初の行の行番号(PL/SQLプログラムは、常に行1から始まり、途中の行が抜けることはありません)。

last_line

フェッチする最後の行の行番号。プログラムの行数を超えると行はフェッチされません。

source

結果の表。行番号で索引が設定されている場合があります。

window

行の'ウィンドウ'(現行のソース行の概数)。

print_arrow

0(ゼロ)以外の場合は、カレント行の前に矢印が出力されます。

buffer

ソース・リストを格納するバッファ。

buflen

バッファの長さ。

pieces

指定したバッファにすべてのソースを格納できない可能性がある場合は、0(ゼロ)以外の値が設定されます。

戻り値

ソース行の索引表。ソース行は、first_lineから格納されます。エラーが発生した場合は、空の表が戻されます。

使用上の注意

(実行されているプログラムの)ソース・コードを取得する最適な方法は、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は、取り出す必要のある追加ピースの数を戻します)。

53.7.31 SYNCHRONIZEファンクション

このファンクションは、ターゲット・プログラムがイベントを通知するまで待機します。info_requestedNULLでない場合は、GET_RUNTIME_INFOをコールします。

構文

DBMS_DEBUG.SYNCHRONIZE (
   run_info       OUT  runtime_info,
   info_requested IN   BINARY_INTEGER := NULL)
  RETURN BINARY_INTEGER;

パラメータ

表53-54 SYNCHRONIZEファンクションのパラメータ

パラメータ 説明

run_info

プログラムに関する情報を書き込むためのデータ構造。デフォルトでは、実行中のプログラムおよび一時停止している行に関する情報が含まれます。

info_requested

デフォルト(info_getStackDepth + info_getLineInfo)以外の情報を要求するためのオプションのビット・フィールド。0 (ゼロ)は、情報を要求しないことを意味します(情報フラグの詳細は、「DBMS_DEBUGの使用上の注意」を参照)。

戻り値

表53-55 SYNCHRONIZEファンクションの戻り値

戻り値 説明

success

正常な完了。

error_timeout

プログラムが実行を開始する前にタイムアウトしました。

error_communication

その他の通信エラー。

53.7.32 TARGET_PROGRAM_RUNNINGプロシージャ

このプロシージャは、ターゲット・セッションが現在ストアド・プロシージャを実行中の場合はTRUE、実行していない場合はFALSEを戻します。

構文

DBMS_DEBUG.TARGET_PROGRAM_RUNNING 
  RETURN BOOLEAN;