68 DBMS_DEBUG_JDWP
The DBMS_DEBUG_JDWP
provides the interface to initiate and control the debugging of PL/SQL stored procedures and Java stored procedures over Java Debug Wire Protocol (JDWP).
68.1 DBMS_DEBUG_JDWP Overview
Oracle supports the debugging of PL/SQL stored procedures and Java stored procedures over JDWP. Using the DBMS_DEBUG_JDWP
package, you can:
-
Retrieve the session ID of the current session and serial number
-
Connect a database session to a debugger over JDWP
-
Set the NLS parameters to change the formats in which PL/SQL program values are represented over JDWP
68.2 DBMS_DEBUG_JDWP Security Model
The debugging user invoking a DBMS_DEBUG_JDWP
subprogram requires a privilege to connect the target database session to the debugger.
Table 68-1 System Privileges
System Privilege | Description |
---|---|
|
Allows a user to connect his current session to a debugger |
|
Allows a user to connect a session by any logon user to a debugger |
In addition, the user can also be granted the following user privilege to debug another user’s session.
Table 68-2 User Privileges
User Privilege | Description |
---|---|
|
Allows a user to connect any of the specified user’s logon sessions to a debugger to debug another user's session or his own |
68.3 Summary DBMS_DEBUG_JDWP Subprograms
This table lists the DBMS_DEBUG_JDWP
subprograms and briefly describes them.
Table 68-3 DBMS_DEBUG_JDWP Package Subprograms
Subprogram | Description |
---|---|
Connects the specified session to the debugger waiting at |
|
Gets the current session's session ID |
|
Gets the current session's session serial number |
|
Disconnects the specified session from any debugger with which it is connected |
|
Gets the value of the specified NLS parameter affecting the format in which |
|
Connects a session to a debugger without having to directly modify an application's code |
|
Sets the value of the specified NLS parameter affecting the format in which |
68.3.1 CONNECT_TCP Procedure
This procedure connects the specified session to the debugger waiting at host:port
.
Syntax
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);
Parameters
Table 68-4 CONNECT_TCP Parameters
Parameter | Description |
---|---|
|
The host name the debugger is waiting at |
|
The port number the debugger is waiting at |
|
Session ID |
|
Session number |
|
Debug role |
|
Debug password |
|
Values:
These may be added together to select multiple option choices. |
|
The ID of the Oracle JDWP extension command set |
Exceptions
Table 68-5 CONNECT_TCP Exceptions
Exception | Description |
---|---|
|
Invalid session ID |
|
Insufficient privilege |
|
Session is already connected to a debugger |
|
Improper value for argument |
|
Improper value for argument |
|
Failure establishing connection to debugger |
Usage Notes
-
To connect the current session to a debugger, you can pass
NULL
to both thesession_id
andsession_serial
parameters. -
To connect a different session, you need to find out its ID and serial. These are available in the
v$plsql_debuggable_sessions
view. The Instance Manager option of Oracle Enterprise Manager is one example of a user interface that displays these values to users. You can also find the values of these for your own session using the CURRENT_SESSION_ID Function and CURRENT_SESSION_SERIAL Function. -
The
debug_role
anddebug_role_pwd
arguments allow the user to name any role as the "debug role", which will be available to privilege checking when checking for permissions to connect the session and when checking permissions available on objects within the debugged session. Both the role and its password are passed here as strings and not as identifiers, so double quotes should not be used but case matters. If the original role name wasn't double-quoted, it should be specified here in upper case. -
An
ORA-30677
indicates that the requested session is already being debugged. It is suggested in this case that the user be asked to confirm that (s)he desires to steal the session from the existing connection, and then either an explicit disconnect call or the use of theconnect_force_connect
option bit can be used to allow the connection to succeed on a second attempt. Note that using theconnect_force_connect
bit will avoid the session being allowed to run freely if it is currently suspended through the debugger - in other words, this bit lets you steal a session from one debugger to another without actually disturbing the state of the session.
68.3.2 CURRENT_SESSION_ID Function
This function gets the current session's session ID
Syntax
DBMS_DEBUG_JDWP.CURRENT_SESSION_ID RETURN PLS_INTEGER;
68.3.3 CURRENT_SESSION_SERIAL Function
This function gets the current session's session number.
Syntax
DBMS_DEBUG_JDWP.CURRENT_SESSION_SERIAL RETURN PLS_INTEGER;
68.3.4 DISCONNECT Procedure
This procedure disconnects the specified session from any debugger with which it is connected.
Syntax
DBMS_DEBUG_JDWP.DISCONNECT( session_id IN PLS_INTEGER := NULL, session_serial IN PLS_INTEGER := NULL);
Parameters
Table 68-6 DISCONNECT Procedure Parameters
Parameter | Description |
---|---|
|
Session ID |
|
Session number |
Usage Notes
-
If the session to disconnect is the current session, the session will be allowed to run freely after disconnecting the debugger. Otherwise, the session will be terminated.
-
The same rights are required for this call as for connect, except when disconnecting the current session and the effective user at the time of the call is the same as the login user of the session where no privilege is required.
68.3.5 GET_NLS_PARAMETER Function
This function gets the value of the specified NLS parameter affecting the format in which the NUMBER
, DATE
, TIME (WITH TIME ZONE)
and TIMESTAMP (WITH TIME ZONE)
runtime values of PL/SQL programs are converted to strings, as they are presented through JDWP.
These values are private to the current session, but further are private to the debugger mechanisms, separate from the values used to convert values within the debugged program itself.
Syntax
DBMS_DEBUG_JDWP.GET_NLS_PARAMETER( name IN VARCHAR2) RETURN VARCHAR2;
Parameters
Table 68-7 GET_NLS_PARAMETER Function Parameters
Parameter | Description |
---|---|
|
Specified NLS parameter |
Usage Notes
-
When any variable value is read or assigned through JDWP, or when either
GET_NLS_PARAMETER Function
orSET_NLS_PARAMETER Procedure
is first invoked in a session, the debugger mechanisms make a private copy of the then-currentNLS_LANGUAGE
,NLS_TERRITORY
,NLS_CALENDAR
,NLS_DATE_LANGUAGE
,NLS_NUMERIC_CHARACTERS
,NLS_TIMESTAMP_FORMAT
,NLS_TIMESTAMP_TZ_FORMAT
,NLS_TIME_FOMAT
andNLS_TIME_TZ_FORMAT
values. These private copies may be read using thisGET_NLS_PARAMETER Function
call and changed using the following call to the SET_NLS_PARAMETER Procedure. -
Once the debugger's private copy of the NLS parameters is established, changes made to the NLS parameters in the current session using the
ALTER SESSION
statement will have no effect on the formatting of values as seen through JDWP. To modify the NLS parameters used for JDWP, one must use theSET_NLS_PARAMETER Procedure
. By the same token, changes made to the debugger's private copy of the NLS parameters usingSET_NLS_PARAMETER Procedure
will have no effect on the debugged program itself. -
Date values are always formatted for JDWP use using the
NLS_TIMESTAMP_FORMAT
. The default format forDATE (NLS_DATE_FORMAT)
used in a session most often does not show the time information that is in fact present in the value, and for debugging purposes it seems beneficial to always display that information.
68.3.6 PROCESS_CONNECT_STRING Procedure
This procedure connects a session to a debugger in two ways, so that you do not have to directly modify the application code.
The two ways are:
-
Using the
ORA_DEBUG_JDWP
environment variable, when running an OCI program -
Setting a web browser cookie called
OWA_DEBUG_<dad>
, when running an application through the PL/SQL Web Gateway
Syntax
DBMS_DEBUG_JDWP.PROCESS_CONNECT_STRING ( connect_string IN VARCHAR2, connect_string_type IN PLS_INTEGER);
Parameters
Table 68-8 PROCESS_CONNECT_STRING Procedure Parameters
Parameter | Description |
---|---|
|
The |
|
Can have the following two values:
|
Exceptions
Table 68-9 PROCESS_CONNECT_STRING Procedure Exceptions
Exception | Description |
---|---|
|
Invalid session ID |
|
Insufficient privilege |
|
Session is already connected to a debugger |
|
Improper value for argument |
|
Improper value for argument |
|
Failure establishing connection to debugger |
|
Improper value for environment variable |
68.3.7 SET_NLS_PARAMETER Procedure
This function sets the value of the specified NLS parameter affecting the format in which NUMBER
, DATE
, TIME (WITH TIME ZONE)
and TIMESTAMP (WITH TIME ZONE)
runtime values of PL/SQL programs are converted to strings as they are presented through JDWP.
These values are private to the current session, but further are private to the debugger mechanisms, separate from the values used to convert values within the debugged program itself.
Syntax
DBMS_DEBUG_JDWP.SET_NLS_PARAMETER( name IN VARCHAR2, value IN VARCHAR2);
Parameters
Table 68-10 SET_NLS_PARAMETER Procedure Parameters
Parameter | Description |
---|---|
|
Specified NLS parameter |
|
Value of specified NLS parameter |
Usage Notes
-
When any variable value is read or assigned through JDWP, or when either
GET_NLS_PARAMETER Function
orSET_NLS_PARAMETER Procedure
is first invoked in a session, the debugger mechanisms make a private copy of the then-currentNLS_LANGUAGE
,NLS_TERRITORY
,NLS_CALENDAR
,NLS_DATE_LANGUAGE
,NLS_NUMERIC_CHARACTERS
,NLS_TIMESTAMP_FORMAT
,NLS_TIMESTAMP_TZ_FORMAT
,NLS_TIME_FOMAT
andNLS_TIME_TZ_FORMAT
values. These private copies may be read by calling the GET_NLS_PARAMETER Function and changed using the following call to theSET_NLS_PARAMETER Procedure
. -
Once the debugger's private copy of the NLS parameters is established, changes made to the NLS parameters in the current session using the
ALTER SESSION
statement will have no effect on the formatting of values as seen through JDWP. To modify the NLS parameters used for JDWP, one must use theSET_NLS_PARAMETER Procedure
. By the same token, changes made to the debugger's private copy of the NLS parameters usingSET_NLS_PARAMETER Procedure
will have no effect on the debugged program itself. -
Date values are always formatted for JDWP use using the
NLS_TIMESTAMP_FORMAT
. The default format forDATE (NLS_DATE_FORMAT)
used in a session most often does not show the time information that is in fact present in the value, and for debugging purposes it seems beneficial to always display that information.