Subject:  PACKAGE DBMS_DEBUG Specification 
Type:  REFERENCE 
Status:  PUBLISHED 
 Content Type:  TEXT/PLAIN 
Creation Date:  05-JAN-1999 
 

PACKAGE:DBMS_DEBUG
~~~~~~~~~~~~~~~~~~
Version/s:  8.0, 8.1   (Notes here based on Oracle8i)
See Also:   [NOTE:67537.1] The Purpose of DB Package Reference Articles
Defined in: dbmspb.sql


 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.)
 
 -----------
 PROCEDURES
 -----------
	<Note.67900.1>  DBMS_DEBUG.PROBE_VERSION 
	<Note.67901.1>  DBMS_DEBUG.SELF_CHECK 
	<Note.67902.1>  DBMS_DEBUG.SET_TIMEOUT 
	<Note.67903.1>  DBMS_DEBUG.INITIALIZE 
	<Note.67904.1>  DBMS_DEBUG.DEBUG_ON 
	<Note.67905.1>  DBMS_DEBUG.DEBUG_OFF 
	<Note.67906.1>  DBMS_DEBUG.ATTACH_SESSION 
	<Note.67907.1>  DBMS_DEBUG.SYNCHRONIZE 
	<Note.67908.1>  DBMS_DEBUG.SHOW_SOURCE 
	<Note.67909.1>  DBMS_DEBUG.GET_MORE_SOURCE 
	<Note.67910.1>  DBMS_DEBUG.PRINT_BACKTRACE 
	<Note.67911.1>  DBMS_DEBUG.PRINT_BACKTRACE 
	<Note.67912.1>  DBMS_DEBUG.CONTINUE 
	<Note.67913.1>  DBMS_DEBUG.SET_BREAKPOINT 
	<Note.67914.1>  DBMS_DEBUG.DELETE_BREAKPOINT 
	<Note.67915.1>  DBMS_DEBUG.DISABLE_BREAKPOINT 
	<Note.67916.1>  DBMS_DEBUG.SHOW_BREAKPOINTS 
	<Note.67917.1>  DBMS_DEBUG.GET_VALUE 
	<Note.67918.1>  DBMS_DEBUG.SET_VALUE 
	<Note.67919.1>  DBMS_DEBUG.ABORT 
	<Note.67920.1>  DBMS_DEBUG.DETACH_SESSION 
	<Note.67921.1>  DBMS_DEBUG.GET_RUNTIME_INFO 
	<Note.67922.1>  DBMS_DEBUG.GET_INDEXES