it is not really intended for you to use -- it is intended to be used by someone who wants to write a PLSQL debugger.

Here is a note on it:

Article-ID: <Note:67899.1>
Alias: PLSQL:DBMS_DEBUG
Circulation: PUBLISHED (EXTERNAL)
Folder: PLSQL
Topic: DBMS_DEBUG Package
Title: PACKAGE DBMS_DEBUG Specification
Document-Type: REFERENCE
Impact: MEDIUM
Skill-Level: CASUAL
Server-Version: 08 to 08.01
Updated-Date: 05-JAN-1999 15:22:38
References:
Shared-Refs:
Authors: AUTO
Attachments: NONE
Content-Type: TEXT/PLAIN
Products: 11/PLSQL;
Platforms: GENERIC;

PACKAGE:DBMS_DEBUG
~~~~~~~~~~~~~~~~~~
Version/s: 8.0, 8.1 (Notes here based on Oracle8i)


OVERVIEW
DBMS_DEBUG is a PL/SQL API to the PL/SQL debugger layer ('Probe') in
the Oracle server. It is intended mainly for vendors implementing
server-side debuggers, and provides a way to debug server-side PL/SQL
(procedures, functions, packages, triggers, anonymous blocks, types,
etc.)
DBMS_DEBUG uses a 'pull' event model: in order to debug server-side
code it is necessary to have two database sessions: a session in which
the code will be executed in debug-mode (known as the target session),
and a second session (known as the debug session) to supervise the
target session.

To use DBMS_DEBUG, the target session first makes the appropriate calls
to initialize itself (described later). This marks the session so that
the PL/SQL interpreter runs in debug-mode and generates debug events
(described later). As debug events are generated, they are posted from
the session. In most cases, debug events require return notification:
the interpreter pauses awaiting a reply.
Meanwhile the debug session must also initialize itself via DBMS_DEBUG:
this tells it what target session to supervise. The debug session may
then call entrypoints in DBMS_DEBUG to read events that were posted
from the target session and to communicate with the target session.

DBMS_DEBUG does not provide any interface to the PL/SQL compiler. But
it does depend on debug information that is optionally generated by
the compiler. Without debug information it is not possible to look at
or modify the values of parameters or variables. There are two ways
to ensure that debug information is generated: via a session switch or
via individual recompilation.
To set the session switch, execute this statement:
ALTER SESSION SET PLSQL_DEBUG=true;
This instructs the compiler to generate debug information for the
remainder of the session. It does not recompile any existing PL/SQL.
To generate debug information for existing PL/SQL code, use one of the
following statements (the second recompiles a package or type body):
ALTER [PROCEDURE | FUNCTION | PACKAGE | TRIGGER | TYPE] <name>
COMPILE DEBUG;
ALTER [PACKAGE | TYPE] <name> COMPILE DEBUG BODY;


The diagrams below give the general idea.
Each box contains a description and the appropriate DBMS_DEBUG call.

Target Session
**************
+--------------------------------------+
| Initialize session for debugging, |
| and generate/specify unique debugID. |
| DBMS_DEBUG.initialize() |
+--------------------------------------+
|
+---------------------------------->|
| V
| +--------------------+-----------------+
| V | V
| +-----------------------+ | +------------------------+
| | Start debugging | | | Stop debugging |
| | DBMS_DEBUG.debug_on() | | | DBMS_DEBUG.debug_off() |
| +-----------------------+ | +------------------------+
| V V V
| +--------------------+-----------------+
| V
| +-------------------------+
| | Execute PL/SQL programs |
| +-------------------------+
| V
+-----------------------------------+



Debug Session
*************
+-----------------------------+
Input: | Initialize |
debugID from --> | DBMS_DEBUG.attach_session() |
target session +-----------------------------+
|
+------------------------------------>|
| +-------------------<+<------------------+
| | | |
| | +--------------------------------+ |
| | | Manipulate breakpoints | |
| | | DBMS_DEBUG.set_breakpoint() | |
| | | DBMS_DEBUG.delete_breakpoint() | |
| | | DBMS_DEBUG.disable_breakpoint()| |
| | | DBMS_DEBUG.enable_breakpoint() | |
| | | DBMS_DEBUG.show_breakpoints() | |
| | +--------------------------------+ |
| | V |
| +------------------->+>------------------+
| |
| V
| +--------------------------------------+
| | Read first event from target session |
| | DBMS_DEBUG.synchronize() |
| +--------------------------------------+
| |
| +---------------------->|
| | +------------------>|
| | | V
| | | +----------------------->+
| | | | |
| | | V |
| | | +------------------------------+ |
| | | | Show stack |-------->+
| | | | DBMS_DEBUG.print_backtrace() | V
| | | +------------------------------+ |
| | | |
| | | +------------------------<+
| | | V V
| | | +------------------------+ |
| | | | Get/set values | |
| | | | DBMS_DEBUG.get_value() |-------------->+
| | | | DBMS_DEBUG.set_value() | V
| | | +------------------------+ |
| | | |
| | | +---------------------------<+
| | | V V
| | | +------------------------+ |
| | | | Manipulate breakpoints |-------------->+
| | | +------------------------+ V
| | | |
| | | +--------------------------<+
| | | V V
| | | +--------------------------+ |
| | | | Show source |------------>+
| | | | DBMS_DEBUG.show_source() | V
| | | +--------------------------+ |
| | | |
| | +----------------------<+-------------------<+
| | |
| | V
| | +--------------------------------------------+
| | | Continue execution and wait for next event |
| | | DBMS_DEBUG.continue() |
| | +--------------------------------------------+
| |
| | +---------------------------------------+
| +- No - | Program terminated? |
| | (event is DBMS_DEBUG.reason_knl_exit) |
| +---------------------------------------+
| |
| Yes
+---------------------------+
next program to debug V
|
+-----------------------------+
| Detach session |
| DBMS_DEBUG.detach_session() |
+-----------------------------+

Control of the interpreter
The interpreter will pause execution in the following places:
1. At startup of the interpreter (so that any deferred breakpoints
may be installed prior to execution)
2. At any line containing an enabled breakpoint
3. At any line where an 'interesting' event occurs. The set of
interesting events is determined by the flags passed to
DBMS_DEBUG.continue (in the 'breakflags' parameter).
See the section on 'Break Flags' below for more details.

Terminology
+ Program unit - a PL/SQL program of any kind (procedure, function,
package, package body, trigger, anonymous block, object type, or
object type body).

General notes:
+ Session termination
There is no event for session termination. Therefore it is the
responsibility of the debug session to check and make sure that
the target session has not terminated. A call to
dbms_debug.synchronize() after the target session has terminated
will cause the debug session to hang until it times out.

+ Deferred operations
The diagram suggests that it is possible to set breakpoints prior
to having a target session. This is true: in this case Probe caches
the breakpoint request and transmits it to the target session at
first synchronization. However note that if a breakpoint request is
deferred in this fashion then:
1. set_breakpoint() does not set the breakpoint number (it can be
obtained later from show_breakpoints() if necesary)
2. set_breakpoint() does not validate the breakpoint request: if
the requested source line does not exist then the error will
silently occur at synchronization and no breakpoint will be
set.

+ Stepping into packages.
Packages are instantiated upon first use, and any initialization
code (in either the package spec or body) is executed at that time.
Thus a call to a procedure/function in a package may look to the
debugger like several calls all on the same line (one call to
initialize the spec if necessary, one to initialize the body if
necessary, and one to call the desired entrypoint).

+ Diagnostic output
To debug Probe, there are 'diagnostics' parameters to some of the
calls in DBMS_DEBUG. These parameters specify whether to place
diagnostic output in the rdbms tracefile. (If output to the rdbms
tracefile is disabled then these parameters will be no-ops.)