External Application Debugging Mode

This debugging mode allows you to dedicate an instance of Visual Studio to debug PL/SQL programs that are called by external applications running on any platform, local or remote. Typically, the procedure is called by a web application on a middle tier.

External applications use one of two possible ways to connect to the Oracle PL/SQL Debugger, the ORA_DEBUG_JDWP config file value or environment variable, which requires no modifications to the PL/SQL program, or the DBMS_DEBUG_JDWP PL/SQL package, which does require modifications to the PL/SQL program.

This section includes the following topics:

How External Application Debugging Works

The Oracle PL/SQL Debugger starts when you select Start Oracle External Application Debugger from the Visual Studio Tools menu. A dialog box appears prompting you to enter the IP address and port number for the computer where Visual Studio is located. This must be the same IP Address and port number that you have provided in the ORA_DEBUG_JDWP config file of the application or environment variable or through a DBMS_DEBUG_JDWP package call inside PL/SQL.

When the external application opens a database connection, the database connects to the Oracle PL/SQL Debugger at the given IP address and port number and eventually the breakpoint is hit, giving control to the developer in Visual Studio.

Note:

It is recommended that only one external application connects to the debugger at a time.

The Debug Location Toolbar displays Oracle Debugger once the Oracle PL/SQL Debugger starts.

Using the ORA_DEBUG_JDWP Config/Environment Variable

The ORA_DEBUG_JDWP variable can be set in the environment of an external application and provides a valid IP address and port number for the computer where Visual Studio is located. When any Oracle application on any operating system connects to Oracle, this variable is read and is passed to the database which then connects back to the Oracle Debugger in Visual Studio, beginning the debugging session.

Using a Environment Variable

Set the value of ORA_DEBUG_JDWP in the format:

host=IP address or host name;port=debugging port number

where:

  • IP address or host name is the Internet Protocol dotted address or host name of the computer running Visual Studio.

  • debugging port number is the TCP port number being used by the PL/SQL debugger.

In the following example, the ORA_DEBUG_JDWP variable is set at the command prompt:

set ORA_DEBUG_JDWP=host=130.35.12.111;port=1234

No spaces are allowed anywhere in the value of the ORA_DEBUG_JDWP variable.

When the external application creates a database connection, the database connects to the Oracle PL/SQL Debugger located in the IP address, 130.35.12.111, and at the TCP port number, 1234, where the Oracle PL/SQL Debugger listens.

Note:

Do not set the ORA_DEBUG_JDWP variable in the Visual Studio runtime environment.

Using a ODP.NET Configuration File Variable

For ODP.NET version 12.1.0.2 or later, ORA_DEBUG_JDWP may be set in the machine.config, web.config or app.config of the application. This has the same effect as setting an environment variable. The configuration file value takes precedence over any environment variable.

Example ODP.NET config file entry:

<oracle.manageddataaccess.client>
  <version number="*">
    <settings>
      <setting name="ORA_DEBUG_JDWP" value="host=130.35.12.111;port=1234"/>
    </settings>
  </version>
</oracle.manageddataaccess.client>

Using the DBMS_DEBUG_JDWP package

The DBMS_DEBUG_JDWP PL/SQL package allows you to control precisely when the database connects or disconnects to the PL/SQL Debugger in Visual Studio. Instead of beginning the debugging session as soon as the application connects to Oracle, this package allows to you wait until a specific point in the PL/SQL code. This is useful when you only want to debug a small portion of a large package, for example. You must add code to your PL/SQL to call the DBMS_DEBUG_JDWP connect and disconnect procedures.

The DBMS_DEBUG_JDWP package provides two procedures for the application to connect and disconnect from the Oracle PL/SQL Debugger.

You must implement these two procedures in your PL/SQL code:

  • Connecting Procedure

    CONNECT_TCP(HOST VARCHAR2, PORT VARCHAR2)

    This procedure allows the database to connect to the Oracle PL/SQL Debugger.

    where:

    • HOST is the host address where the Oracle PL/SQL Debugger resides.

    • PORT is the is the TCP port number for PL/SQL debugging. You must specify the same port number when you start the debugger.

    The application usually opens a database connection. The database connects to the debugger when it executes the DBMS_DEBUG_JDWP.CONNECT_TCP method.

  • Disconnecting Procedure

    DISCONNECT()

    This procedure allows the database to disconnect from the Oracle PL/SQL Debugger.

Requirements for External Application Debugging

Prior to using External Database Debugging, perform all the setup requirements listed in PL/SQL Debugging Setup.

Before Using External Application Debugging Mode

Before using external application debugging mode, you must do the following:

  • Set breakpoints.

    To use external application debugging, you must set one breakpoint in the PL/SQL program being called. If you have a second instance of Visual Studio being used to debug .NET code, you may wish to set a breakpoint at some point after the PL/SQL program is executed.

  • Set the ORA_DEBUG_JDWP environment variable in the environment of the external application or set the ORA_DEBUG_JDWP ODP.NET configuration file variable.

    See Using the ORA_DEBUG_JDWP Config/Environment Variable.

    or

  • Modify the PL/SQL being debugged to add calls to DBMS_DEBUG_JDWP.CONNECT_TCP (with the correct IP address and port number) and DBMS_DEBUG_JDWP.DISCONNECT.

    See Using the DBMS_DEBUG_JDWP package.

Debugging Using External Application Debugging Mode

To debug using External Application Debugging Mode, follow all the steps in the Debugging Setup Checklist.