Chapter 10. DBMS_DEBUG
Prev   Next

Chapter 10. DBMS_DEBUG

Table of Contents

10.1. Overview
10.2. Types
10.2.1. breakpoint_info
10.2.2. program_info
10.2.3. runtime_info
10.3. Procedures and Functions
10.3.1. ATTACH_SESSION
10.3.2. CONTINUE
10.3.3. DEBUG_OFF
10.3.4. DEBUG_ON
10.3.5. DELETE_BREAKPOINT
10.3.6. DETACH_SESSION
10.3.7. DISABLE_BREAKPOINT
10.3.8. ENABLE_BREAKPOINT
10.3.9. GET_RUNTIME_INFO
10.3.10. GET_VALUE
10.3.11. INITIALIZE
10.3.12. PRINT_BACKTRACE
10.3.13. SET_BREAKPOINT
10.3.14. SHOW_BREAKPOINTS
10.3.15. SYNCHRONIZE

This chapter briefly introduces the DBMS_DEBUG package, and describes how to use the procedures and functions of the package.

10.1. Overview

DBMS_DEBUG debugs PSM programs using two sessions, a target session that executes a PSM program and a debug session that receives debugging information from the target session.

The following are constants defined in DBMS_DEBUG.

SUCCESS                     CONSTANT BINARY_INTEGER := 0;
ERROR_BOGUS_FRAME           CONSTANT BINARY_INTEGER := 1;
ERROR_NO_DEBUG_INFO         CONSTANT BINARY_INTEGER := 2;
ERROR_NO_SUCH_OBJECT        CONSTANT BINARY_INTEGER := 3;
ERROR_UNKNOWN_TYPE          CONSTANT BINARY_INTEGER := 4;
ERROR_INDEXED_TABLE         CONSTANT BINARY_INTEGER := 5;
ERROR_ILLEGAL_INDEX         CONSTANT BINARY_INTEGER := 6;
ERROR_NULLCOLLECTION        CONSTANT BINARY_INTEGER := 7;
ERROR_NULLVALUE             CONSTANT BINARY_INTEGER := 8;
ERROR_ILLEGAL_VALUE         CONSTANT BINARY_INTEGER := 9;
ERROR_ILLEGAL_NULL          CONSTANT BINARY_INTEGER := 10;
ERROR_VALUE_MALFORMED       CONSTANT BINARY_INTEGER := 11;
ERROR_OTHER                 CONSTANT BINARY_INTEGER := 12;
ERROR_NAME_INCOMPLETE       CONSTANT BINARY_INTEGER := 13;
ERROR_NO_SUCH_BREAKPT       CONSTANT BINARY_INTEGER := 14;
ERROR_IDLE_BREAKPT          CONSTANT BINARY_INTEGER := 15;
ERROR_BAD_HANDLE            CONSTANT BINARY_INTEGER := 16;
ERROR_UNIMPLEMENTED         CONSTANT BINARY_INTEGER := 17;
ERROR_DEFERRED              CONSTANT BINARY_INTEGER := 18;
ERROR_EXCEPTION             CONSTANT BINARY_INTEGER := 19;
ERROR_COMMUNICATION         CONSTANT BINARY_INTEGER := 20;
ERROR_TIMEOUT               CONSTANT BINARY_INTEGER := 21;
ILLEGAL_INIT                CONSTANT BINARY_INTEGER := 22;
PIPE_CREATION_FAILURE       CONSTANT BINARY_INTEGER := 23;
PIPE_SEND_FAILURE           CONSTANT BINARY_INTEGER := 24;
PIPE_RECEIVE_FAILURE        CONSTANT BINARY_INTEGER := 25;
PIPE_DATATYPE_MISMATCH      CONSTANT BINARY_INTEGER := 26;
PIPE_DATA_ERROR             CONSTANT BINARY_INTEGER := 27;

  • Breakflags

    • Prototypes

      BREAK_DEFAULT               CONSTANT BINARY_INTEGER := 0;
BREAK_NEXT_LINE             CONSTANT BINARY_INTEGER := 1;
BREAK_ANY_CALL              CONSTANT BINARY_INTEGER := 2;
BREAK_ANY_RETURN            CONSTANT BINARY_INTEGER := 3;
BREAK_RETURN                CONSTANT BINARY_INTEGER := 4;
BREAK_EXCEPTION             CONSTANT BINARY_INTEGER := 5;
BREAK_HANDLER               CONSTANT BINARY_INTEGER := 6;
ABORT_EXECUTION             CONSTANT BINARY_INTEGER := 7;

    • Arguments

      The following describes the breakflags arguments of DBMS_DEBUG.CONTINUE.

      ArgumentDescription
      BREAK_DEFAULTJumps to the specified next breakpoint.
      BREAK_NEXT_LINESteps over to the next line.
      BREAK_ANY_CALLSteps into the next line.
      BREAK_ANY_RETURNExecutes the program until the end of the current entry point (step out).
      BREAK_RETURNUnused in the current version.
      BREAK_EXCEPTIONUnused in the current version.
      BREAK_HANDLERUnused in the current version.
      ABORT_EXECUTIONImmediately terminates the program.

  • Information Flags

    • Prototypes

      INFO_GET_STACK_DEPTH        CONSTANT BINARY_INTEGER := 0;
INFO_GET_BREAK_POINT        CONSTANT BINARY_INTEGER := 1;
INFO_GET_LINE_INFO          CONSTANT BINARY_INTEGER := 2;
INFO_GET_ALL                CONSTANT BINARY_INTEGER := 3;

    • Arguments

      The following describes the flags for getting various runtime information fields.

      ArgumentDescription
      INFO_GET_STACK_DEPTHGets depth of the current stack.
      INFO_GET_BREAK_POINTGets the ID of the current break point where the target program is stopped at.
      INFO_GET_LINE_INFOGets information about the line that is currently being processed.
      INFO_GET_ALLGets all information of STACK_DEPTH, _BREAK_POINT, and LINE_INFO.

10.2. Types

This section describes the types provided by the DBMS_DEBUG package, in alphabetical order.

10.2.1. breakpoint_info

Used to get breakpoint information.

Details about the breakpoint_info type are as follows:

  • Prototype

    TYPE breakpoint_info IS RECORD 
(
    name        VARCHAR2(30),
    owner       VARCHAR2(30),
    line#       BINARY_INTEGER,
    status      BINARY_INTEGER
);

  • Field

    FieldDescription
    namePSM program name.
    ownerPSM program owner.
    line#Line number.
    status

    Current breakpoint status.

    • breakpoint_status_active

    • breakpoint_status_disabled

10.2.2. program_info

Indicates a position in a PSM program. A specific line position is used to configure stack backtrace, break point, etc.

Details about the program_info type are as follows:

  • Prototype

    TYPE program_info IS RECORD 
(
    namespace   BINARY_INTEGER,
    name        VARCHAR2(30),
    owner       VARCHAR2(30),
    line#       BINARY_INTEGER,
    entrypointname   VARCHAR2(30)
);

  • Field

    FieldDescription
    namespaceUnused in the current version.
    namePSM program name.
    ownerPSM program owner.
    line#Line number.
    statusUnused in the current version.

10.2.3. runtime_info

Indicates information about the currently running PSM program.

Details about the runtime_info type are as follows:

  • Prototype

    TYPE runtime_info IS RECORD 
(
     line#            BINARY_INTEGER,
     terminated       BINARY_INTEGER,
     breakpoint       BINARY_INTEGER,
     stackdepth       BINARY_INTEGER,
     program          program_info
);

  • Field

    FieldDescription
    line#Line number.
    terminatedWhether the target program has been terminated or not.
    breakpointUnique breakpoint ID.
    stackdepthStack depth of the currently running program.
    programProgram location in the source code.

10.3. Procedures and Functions

This section describes the procedures and functions provided by the DBMS_DEBUG package, in alphabetical order.

10.3.1. ATTACH_SESSION

Allows a debug session to access the target session.

Details about the ATTACH_SESSION procedure are as follows:

  • Prototype

    DBMS_DEBUG.ATTACH_SESSION 
(
    debug_session_id  IN VARCHAR2,
    diagnostics       IN BINARY_INTEGER := 0
);

  • Parameter

    ParameterDescription
    debug_session_id

    Target session ID returned by the INITIALIZE function executed on the target session.

    Used when a debug session searches for a specific target session.

    diagnosticsUnused in the current version.

10.3.2. CONTINUE

Executes and completes a PSM program of the target session using breakflags.

Details about the CONTINUE function are as follows:

  • Prototype

    DBMS_DEBUG.CONTINUE 
(
    run_info         IN OUT  runtime_info,
    breakflags       IN      BINARY_INTEGER,
    info_requested   IN      BINARY_INTEGER := NULL
) 
RETURN BINARY_INTEGER;

  • Parameter

    ParameterDescription
    run_infoInformation about the currently running PSM program.
    breakflagsFlags that specify an action of Continue. For more information, refer to "Breakflags".
    info_requestedFlag that specifies the type of information requested through the run_info argument. For more information, refer to "Information Flags".

  • Return Value

    ValueDescription
    0Success.

10.3.3. DEBUG_OFF

Ends debugging for the target session.

Details about the DEBUG_OFF procedure are as follows:

  • Prototype

    DBMS_DEBUG.DEBUG_OFF

10.3.4. DEBUG_ON

A target session starts debugging in this procedure.

Details about the DEBUG_ON procedure are as follows:

  • Prototype

    DBMS_DEBUG.DEBUG_ON 
(
    no_client_side_plsql_engine     BOOLEAN := TRUE,
    immediate                       BOOLEAN := FALSE
);

  • Parameter

    ParameterDescription
    no_client_side_plsql_engineUnused in the current version.
    immediateUnused in the current version.

10.3.5. DELETE_BREAKPOINT

Deletes a breakpoint.

Details about the DELETE_BREAKPOINT function are as follows:

  • Prototype

    DBMS_DEBUG.DELETE_BREAKPOINT
          ( breakpoint IN BINARY_INTEGER ) RETURN
          BINARY_INTEGER;

  • Parameter

    ParameterDescription
    breakpointNumber of the breakpoint to delete.

  • Return Value

    ValueDescription
    0Success.

10.3.6. DETACH_SESSION

Ends debugging for a target PSM program. This procedure can be called at any time and does not terminate the target program. Note that if this procedure is called while the target program is running, the program hangs.

Details about the DETACH_SESSION procedure are as follows:

  • Prototype

    DBMS_DEBUG.DETACH_SESSION

10.3.7. DISABLE_BREAKPOINT

Disables a breakpoint without deleting it.

Details about the DISABLE_BREAKPOINT function are as follows:

  • Prototype

    DBMS_DEBUG.DISABLE_BREAKPOINT
          ( breakpoint IN BINARY_INTEGER ) RETURN
          BINARY_INTEGER;

  • Parameter

    ParameterDescription
    breakpointBreakpoint number set using the SET_BREAKPOINT function.

  • Return Value

    ValueDescription
    0Success.

10.3.8. ENABLE_BREAKPOINT

Enables a disabled breakpoint.

Details about the ENABLE_BREAKPOINT function are as follows:

  • Prototype

    DBMS_DEBUG.ENABLE_BREAKPOINT
          ( breakpoint IN BINARY_INTEGER ) RETURN
          BINARY_INTEGER;

  • Parameter

    ParameterDescription
    breakpointBreakpoint number set using the SET_BREAKPOINT function.

  • Return Value

    ValueDescription
    0Success.

10.3.9. GET_RUNTIME_INFO

Gets information about the currently running program. The retrieved information varies according to the info_requested value.

Details about the GET_RUNTIME_INFO function are as follows:

  • Prototype

    DBMS_DEBUG.GET_RUNTIME_INFO
          ( info_requested IN BINARY_INTEGER, run_info OUT runtime_info )
          RETURN BINARY_INTEGER;

  • Parameter

    ParameterDescription
    info_requestedFlag that specifies the type of information requested through the run_info argument. For more information, refer to "Information Flags".
    run_infoInformation about the currently running PSM program.

  • Return Value

    ValueDescription
    0Success.

10.3.10. GET_VALUE

Gets a variable value from the currently running program.

Details about the GET_VALUE function are as follows:

  • Prototype

    DBMS_DEBUG.GET_VALUE
          ( variable_name IN VARCHAR2, frame# IN BINARY_INTEGER, scalar_value
          OUT VARCHAR2, format IN VARCHAR2 := NULL ) RETURN
          BINARY_INTEGER;

  • Parameter

    ParameterDescription
    variable_nameVariable name.
    frame#Unused in the current version.
    scalar_valueUnused in the current version.
    formatUnused in the current version.

  • Return Value

    ValueDescription
    0Success.
    ERROR_ILLEGAL_VALUEFailure.

10.3.11. INITIALIZE

Initializes a target session for debugging and returns the session ID.

Details about the INITIALIZE function are as follows:

  • Prototype

    DBMS_DEBUG.INITIALIZE
          ( debug_session_id IN VARCHAR2, diagnostics IN BINARY_INTEGER := 0 )
          RETURN BINARY_INTEGER;

  • Parameter

    ParameterDescription
    debug_session_id

    ID of the session that a debug session will access.

    If this parameter is NULL, a unique ID is created.

    diagnosticsUnused in the current version.

  • Return Value

    ValueDescription
    Newly registered target session IDID of the session that a debug session will access.

10.3.12. PRINT_BACKTRACE

Returns the call stack of the currently running program. This procedure can only be called while the program is running.

Details about the PRINT_BACKTRACE procedure are as follows:

  • Prototype

    DBMS_DEBUG.PRINT_BACKTRACE
          ( listing IN OUT VARCHAR2 );

  • Parameter

    ParameterDescription
    listingVARCHAR2 buffer with embedded newlines.

10.3.13. SET_BREAKPOINT

Sets a breakpoint in the currently running program. When the breakpoint is reached, the target program stops running and waits.

Details about the SET_BREAKPOINT function are as follows:

  • Prototype

    DBMS_DEBUG.SET_BREAKPOINT 
(
    program           IN  program_info,
    line#             IN  BINARY_INTEGER,
    breakpoint#       OUT BINARY_INTEGER,
    fuzzy             IN  BINARY_INTEGER := 0,
    iterations        IN  BINARY_INTEGER := 0
) 
RETURN BINARY_INTEGER;

  • Parameter

    ParameterDescription
    programInformation about a PSM program for which a breakpoint is set.
    line#Line number of the breakpoint.
    breakpoint#Unique ID of the breakpoint.
    fuzzyUnused in the current version.
    iterationsUnused in the current version.

  • Return Value

    ValueDescription
    0Success.
    ERROR_IDLE_BREAKPTReturned when no breakpoint has been set.

10.3.14. SHOW_BREAKPOINTS

Returns a list of breakpoints. There are two overloaded procedures.

Details about the SHOW_BREAKPOINTS procedure are as follows:

  • Prototype

    DBMS_DEBUG.SHOW_BREAKPOINTS
          ( listing IN OUT VARCHAR2 ); DBMS_DEBUG.SHOW_BREAKPOINTS ( listing
          OUT breakpoint_table );

  • Parameter

    ParameterDescription
    listing

    VARCHAR2 buffer with embedded newlines or indexed-table of breakpoint entries.

    A unique breakpoint ID becomes the index.

10.3.15. SYNCHRONIZE

Waits for a signal from the target program.

Details about the SYNCHRONIZE function are as follows:

  • Prototype

    DBMS_DEBUG.SYNCHRONIZE
          ( run_info OUT runtime_info, info_requested IN BINARY_INTEGER :=
          NULL ) RETURN BINARY_INTEGER;

  • Parameter

    ParameterDescription
    run_infoInformation about the currently running PSM program.
    info_requestedFlag that specifies the type of information requested through the run_info argument. For more information, refer to "Information Flags".

  • Return Value

    ValueDescription
    0Success.
Prev   Next
Chapter 9. DBMS_DDL Home Chapter 11. DBMS_ERRLOG