1. PL/SQLパッケージおよびタイプ・リファレンス
  2. DBMS_DEBUG_JDWP

54 DBMS_DEBUG_JDWP

DBMS_DEBUG_JDWPは、Java Debug Wire Protocol (JDWP)を介してPL/SQLストアド・プロシージャとJavaストアド・プロシージャのデバッグを開始および制御するためのインタフェースを提供します。

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

54.1 DBMS_DEBUG_JDWPの概要

Oracleでは、JDWPを介したPL/SQLストアド・プロシージャおよびJavaストアド・プロシージャのデバッグをサポートしています。DBMS_DEBUG_JDWPパッケージを使用すると、次のことを実行できます。

  • 現在のセッションのセッションIDおよびシリアル番号を取得します。

  • JDWPを介してデバッガにデータベース・セッションを接続します。

  • PL/SQLプログラムの値がJDWPを介して表示される形式を変更するようにNLSパラメータを設定します。

54.2 DBMS_DEBUG_JDWPのセキュリティ・モデル

DBMS_DEBUG_JDWPサブプログラムを起動するデバッグ・ユーザーには、ターゲット・データベース・セッションをデバッガに接続する権限が必要です。

表54-1 システム権限

システム権限 説明

DEBUG CONNECT SESSION

ユーザーが現在のセッションをデバッガに接続することを許可します。

DEBUG CONNECT ANY

ユーザーがログオン・ユーザーによるセッションをデバッガに接続することを許可します。

また、ユーザーに、別のユーザーのセッションをデバッグするための次のユーザー権限を付与することもできます。

表54-2 ユーザー権限

ユーザー権限 説明

DEBUG CONNECT ON USER <user>

ユーザーが別のユーザーまたは自分のセッションをデバッグするために、指定されたユーザーのログオン・セッションのいずれかをデバッガに接続することを許可します。

54.3 DBMS_DEBUG_JDWPサブプログラムの要約

この表は、DBMS_DEBUG_JDWPサブプログラムを示し、簡単に説明しています。

表54-3 DBMS_DEBUG_JDWPパッケージのサブプログラム

サブプログラム 説明

CONNECT_TCPプロシージャ

指定されたセッションを、host:portで待機しているデバッガに接続します。

CURRENT_SESSION_IDファンクション

現在のセッションのセッションIDを取得します。

CURRENT_SESSION_SERIALファンクション

現在のセッションのセッション・シリアル番号を取得します。

DISCONNECTプロシージャ

指定されたセッションが接続されているデバッガからこれを切断します。

GET_NLS_PARAMETERファンクション

PL/SQLプログラムのNUMBER、DATE、TIME (WITH TIME ZONE)およびTIMESTAMP (WITH TIME ZONE)の実行時の値がJDWPを介して表示される文字列に変換される形式に影響を与える、指定されたNLSパラメータの値を取得します。

PROCESS_CONNECT_STRINGプロシージャ

直接アプリケーション・コードを変更せずに、セッションをデバッガに接続します。

SET_NLS_PARAMETERプロシージャ

PL/SQLプログラムのNUMBER、DATE、TIME (WITH TIME ZONE)およびTIMESTAMP (WITH TIME ZONE)の実行時の値がJDWPを介して表示される文字列に変換される形式に影響を与える、指定されたNLSパラメータの値を設定します。

54.3.1 CONNECT_TCPプロシージャ

このプロシージャは、指定されたセッションを、host:portで待機しているデバッガに接続します。

構文

DBMS_DEBUG_JDWP.CONNECT_TCP(
   host                 IN  VARCHAR2,
   port                 IN  VARCHAR2,
   session_id           IN  PLS_INTEGER := NULL,
   session_serial       IN  PLS_INTEGER := NULL,
   debug_role           IN  VARCHAR2  := NULL,
   debug_role_pwd       IN  VARCHAR2  := NULL,
   option_flags         IN  PLS_INTEGER := 0,
   extensions_cmd_set   IN  PLS_INTEGER := 128);

パラメータ

表54-4 CONNECT_TCPのパラメータ

パラメータ 説明

host

デバッガが待機しているホスト名

port

デバッガが待機しているポート番号

session_id

セッションID

session_serial

セッション番号

debug_role

デバッグ・ロール

debug_role_pwd

デバッグ・パスワード

option_flags

値:

  • 1: 次のクライアント/サーバー・リクエストが開始されるまでプログラムを中断しません。これを使用すると、独自のコードのみの表示を希望するエンド・ユーザーに起動シーケンスを見せないようにすることができます。

  • 2: セッションがデバッガに接続されているように見えても接続を強制します。これは、人が操作する確認ステップが発生した後に指定する場合にのみ適しています。つまり、このオプションを指定しない試行によりORA-30677が発生した場合に、ユーザーが確認すると、このビット・セットで再試行されます。

これらは、複数のオプションを選択できるように一緒に追加できます。

extensions_cmd_set

Oracle JDWP拡張コマンド・セットのID

例外

表54-5 CONNECT_TCPの例外

例外 説明

ORA-00022

セッションIDが無効です。

ORA-01031

権限が不十分です。

ORA-30677

セッションはすでにデバッガに接続されています。

ORA-30681

引数EXTENSIONS_CMD_SETの値が適切ではありません。

ORA-30682

引数OPTION_FLAGSの値が適切ではありません。

ORA-30683

デバッガへの接続の確立で障害が発生しました。

使用上のノート

  • 現在のセッションをデバッガに接続するには、session_idパラメータとsession_serialパラメータの両方にNULLを渡します。

  • 別のセッションを接続するには、そのIDとシリアルを確認する必要があります。これらは、v$plsql_debuggable_sessionsビューで入手できます。これらの値をユーザーが確認できるユーザー・インタフェースの例として、Oracle Enterprise Managerのインスタンス・マネージャ・オプションがあります。また、自分自身のセッションのこれらの値を確認するには、CURRENT_SESSION_IDファンクションおよびCURRENT_SESSION_SERIALファンクションを使用することもできます。

  • debug_role引数およびdebug_role_pwd引数を使用すると、ロールに「debug role」という名前を付けることができます。これにより、セッションに接続するための権限のチェック、およびデバッグ対象のセッション内のオブジェクトで使用可能な権限のチェックを行う場合に、チェックするための権限を入手できます。ロールとそのパスワードはここでは識別子ではなく、文字列として渡されるため、二重引用符は使用できませんが、大/小文字は区別されます。元のロール名が二重引用符で囲まれていなかった場合は、ここでは大文字で指定する必要があります。

  • ORA-30677は、要求されたセッションがすでにデバッグされていることを示します。この場合、ユーザーに既存の接続からセッションをスティールすることを確認するよう求めることをお薦めします。明示的な切断コールまたはconnect_force_connectオプション・ビットを使用すると、接続が2番目の試行を実行することが可能になります。connect_force_connectビットを使用すると、セッションがデバッガを介して現在停止されている場合に自由に実行されなくなります。つまり、このビットを使用すると、セッションの状態に実際に影響を与えることなく、デバッガ間でセッションをスティールできます。

54.3.2 CURRENT_SESSION_IDファンクション

このファンクションは、現在のセッションのセッションIDを取得します。

構文

DBMS_DEBUG_JDWP.CURRENT_SESSION_ID
  RETURN PLS_INTEGER;

54.3.3 CURRENT_SESSION_SERIALファンクション

このファンクションは、現在のセッションのセッション番号を取得します。

構文

DBMS_DEBUG_JDWP.CURRENT_SESSION_SERIAL
  RETURN PLS_INTEGER;

54.3.4 DISCONNECTプロシージャ

このプロシージャは、指定されたセッションが接続されているデバッガからこれを切断します。

構文

DBMS_DEBUG_JDWP.DISCONNECT(
   session_id        IN  PLS_INTEGER  := NULL,
   session_serial    IN  PLS_INTEGER := NULL);

パラメータ

表54-6 DISCONNECTプロシージャのパラメータ

パラメータ 説明

session_id

セッションID

session_serial

セッション番号

使用上のノート

  • 切断するセッションが現在のセッションの場合は、デバッガの切断後にセッションを自由に実行できます。それ以外の場合、セッションは終了します。

  • 現在のセッションを切断する場合、およびコール時の有効なユーザーが権限が必要ないセッションのログイン・ユーザーと同じ場合を除いて、接続に関してはこのコールに同じ権限が必要です。

54.3.5 GET_NLS_PARAMETERファンクション

このファンクションは、PL/SQLプログラムのNUMBER、DATE、TIME (WITH TIME ZONE)およびTIMESTAMP (WITH TIME ZONE)の実行時の値がJDWPを介して表示される文字列に変換される形式に影響を与える、指定されたNLSパラメータの値を取得します。

これらの値は、現在のセッション専用ですが、デバッガ・メカニズム専用でもあります。デバッグ対象のプログラム内の値の変換に使用される値とは異なります。

構文

DBMS_DEBUG_JDWP.GET_NLS_PARAMETER(
   name   IN  VARCHAR2)
  RETURN VARCHAR2;

パラメータ

表54-7 GET_NLS_PARAMETERファンクションのパラメータ

パラメータ 説明

name

指定されたNLSパラメータ

使用上のノート

  • 変数値がJDWPを介して読み込まれるまたは割り当てられる場合、またはGET_NLS_PARAMETERファンクションまたはSET_NLS_PARAMETERプロシージャがセッションで最初に起動される場合は、デバッガ・メカニズムはNLS_LANGUAGE、NLS_TERRITORY、NLS_CALENDAR、NLS_DATE_LANGUAGE、NLS_NUMERIC_CHARACTERS、NLS_TIMESTAMP_FORMAT、NLS_TIMESTAMP_TZ_FORMAT、NLS_TIME_FOMATおよびNLS_TIME_TZ_FORMATのその時点で最新の値のプライベート・コピーを作成します。これらのプライベート・コピーは、このGET_NLS_PARAMETERファンクションコールを使用して読み取り、SET_NLS_PARAMETERプロシージャに対する次のコールを使用して変更できます。

  • デバッガのNLSパラメータのプライベート・コピーが作成されると、ALTER SESSION文を使用して現在のセッションのNLSパラメータに加えた変更は、JDWPを介して表示される値の形式に影響を与えません。JDWPで使用されるNLSパラメータを変更するには、SET_NLS_PARAMETERプロシージャを使用する必要があります。同じトークンによって、SET_NLS_PARAMETERプロシージャを使用してデバッガのNLSパラメータのプライベート・コピーに加えた変更は、デバッグ対象のプログラム自体には影響を与えません。

  • 日付値は常にNLS_TIMESTAMP_FORMATを使用してJDWPに対して書式設定されます。セッションで使用されるDATE (NLS_DATE_FORMAT)のデフォルトの書式は、ほとんどの場合、実際には値で表示される時間情報を示しません。デバッグ目的では、その情報を常に表示すると役立ちます。

54.3.6 PROCESS_CONNECT_STRINGプロシージャ

このプロシージャは、2つの方法でセッションをデバッガに接続するため、直接アプリケーション・コードを変更する必要はありません。

この2つの方法は、次のとおりです。

  • OCIプログラムの実行時にORA_DEBUG_JDWP環境変数を使用します。

  • PL/SQL Webゲートウェイを介してアプリケーションを実行するときに、OWA_DEBUG_<dad>というWebブラウザのCookieを設定します。

構文

DBMS_DEBUG_JDWP.PROCESS_CONNECT_STRING (
   connect_string          IN  VARCHAR2,
   connect_string_type     IN  PLS_INTEGER);

パラメータ

表54-8 PROCESS_CONNECT_STRINGプロシージャのパラメータ

パラメータ 説明

connect_string

接続するデバッガのホストおよびポート番号などのJDWP接続情報を含む、ORA_DEBUG_JDWP環境変数またはOWA_DEBUG_<dad> Cookieの値。

connect_string_type
次の2つの値を使用できます。

  • 接続文字列値をORA_DEBUG_JDWP環境から取得する場合は、1。

  • 値をOWA_DEBUG_<dad> Cookieから取得する場合は、2。

例外

表54-9 PROCESS_CONNECT_STRINGプロシージャの例外

例外 説明

ORA-00022

セッションIDが無効です。

ORA-01031

権限が不十分です。

ORA-30677

セッションはすでにデバッガに接続されています。

ORA-30681

引数EXTENSIONS_CMD_SETの値が適切ではありません。

ORA-30682

引数OPTION_FLAGSの値が適切ではありません。

ORA-30683

デバッガへの接続の確立で障害が発生しました。

ORA-30689

環境変数ORA_DEBUG_JDWPの値が適切ではありません。

54.3.7 SET_NLS_PARAMETERプロシージャ

このファンクションは、PL/SQLプログラムのNUMBER、DATE、TIME (WITH TIME ZONE)およびTIMESTAMP (WITH TIME ZONE)の実行時の値がJDWPを介して表示される文字列に変換される形式に影響を与える、指定されたNLSパラメータの値を設定します。

これらの値は、現在のセッション専用ですが、デバッガ・メカニズム専用でもあります。デバッグ対象のプログラム内の値の変換に使用される値とは異なります。

構文

DBMS_DEBUG_JDWP.SET_NLS_PARAMETER(
   name      IN  VARCHAR2,
   value     IN  VARCHAR2);

パラメータ

表54-10 SET_NLS_PARAMETERプロシージャのパラメータ

パラメータ 説明

name

指定されたNLSパラメータ

value

指定されたNLSパラメータの値

使用上のノート

  • 変数値がJDWPを介して読み込まれるまたは割り当てられる場合、またはGET_NLS_PARAMETERファンクションまたはSET_NLS_PARAMETERプロシージャがセッションで最初に起動される場合は、デバッガ・メカニズムはNLS_LANGUAGE、NLS_TERRITORY、NLS_CALENDAR、NLS_DATE_LANGUAGE、NLS_NUMERIC_CHARACTERS、NLS_TIMESTAMP_FORMAT、NLS_TIMESTAMP_TZ_FORMAT、NLS_TIME_FOMATおよびNLS_TIME_TZ_FORMATのその時点で最新の値のプライベート・コピーを作成します。これらのプライベート・コピーは、GET_NLS_PARAMETERファンクションをコールして読み取り、SET_NLS_PARAMETERプロシージャに対する次のコールを使用して変更できます。

  • デバッガのNLSパラメータのプライベート・コピーが作成されると、ALTER SESSION文を使用して現在のセッションのNLSパラメータに加えた変更は、JDWPを介して表示される値の形式に影響を与えません。JDWPで使用されるNLSパラメータを変更するには、SET_NLS_PARAMETERプロシージャを使用する必要があります。同じトークンによって、SET_NLS_PARAMETERプロシージャを使用してデバッガのNLSパラメータのプライベート・コピーに加えた変更は、デバッグ対象のプログラム自体には影響を与えません。

  • 日付値は常にNLS_TIMESTAMP_FORMATを使用してJDWPに対して書式設定されます。セッションで使用されるDATE (NLS_DATE_FORMAT)のデフォルトの書式は、ほとんどの場合、実際には値で表示される時間情報を示しません。デバッグ目的では、その情報を常に表示すると役立ちます。