PROBE_VERSION Procedure

This procedure returns the version number of DBMS_DEBUG on the server.

Syntax

DBMS_DEBUG.PROBE_VERSION (
major out BINARY_INTEGER,
minor out BINARY_INTEGER);

Parameters

Table 10-2 PROBE_VERSION Procedure Parameters

Parameter

Description

major

Major version number.

minor

Minor version number: increments as functionality is added.

SELF_CHECK Procedure

This procedure performs an internal consistency check. SELF_CHECK also runs a communications test to ensure that the Probe processes are able to communicate.

If SELF_CHECK does not return successfully, then an incorrect version of DBMS_DEBUG was probably installed on this server. The solution is to install the correct version (pbload.sql loads DBMS_DEBUG and the other relevant packages).

Syntax

DBMS_DEBUG.SELF_CHECK (
timeout IN binary_integer := 60);

Parameters

Table 10-3 SELF_CHECK Procedure Parameters

Parameter

Description

timeout

The timeout to use for the communication test. Default is 60 seconds.

Exceptions

Table 10-4 SELF_CHECK Procedure Exceptions

Exception

Description

OER-6516

Probe version is inconsistent.

pipe_creation_failure

Could not create a pipe.

pipe_send_failure

Could not write data to the pipe.

pipe_receive_failure

Could not read data from the pipe.

pipe_datatype_mismatch

Datatype in the pipe was wrong.

pipe_data_error

Data got garbled in the pipe.

All of these exceptions are fatal. They indicate a serious problem with Probe that prevents it from working correctly.

SET_TIMEOUT Function

This function sets the timeout value and returns the new timeout value.

However, this does not work for nonpersistent programs (for example, anonymous blocks and trigger invocation blocks). For nonpersistent programs, call SHOW_SOURCE. There are two flavors: one returns an indexed table of source lines, and the other returns a packed (and formatted) buffer.

Syntax

Parameters

Table 10-11 SHOW_SOURCE Procedure Parameters

Line number of first line to fetch. (PL/SQL programs always start at line 1 and have no holes.)

last_line

Line number of last line to fetch. No lines are fetched past the end of the program.

source

The resulting table, which may be indexed by line#.

Returns

An indexed table of source-lines. The source lines are stored starting at first_line. If any error occurs, then the table is empty.

Usage Notes

This second overloading of SHOW_SOURCE returns the source in a formatted buffer, complete with line-numbers. It is faster than the indexed table version, but it does not guarantee to fetch all the source.

If the source does not fit in bufferlength (buflen), then additional pieces can be retrieved using the GET_MORE_SOURCE procedure (pieces returns the number of additional pieces that need to be retrieved).

Syntax

DBMS_DEBUG.SHOW_SOURCE (
first_line IN BINARY_INTEGER,
last_line IN BINARY_INTEGER,
window IN BINARY_INTEGER,
print_arrow IN BINARY_INTEGER,
buffer IN OUT VARCHAR2,
buflen IN BINARY_INTEGER,
pieces OUT BINARY_INTEGER);

Parameters

Table 10-12 SHOW_SOURCE Procedure Parameters

Parameter

Description

first_line

Smallest line-number to print.

last_line

Largest line-number to print.

window

'Window' of lines (the number of lines around the current source line).

print_arrow

Nonzero means to print an arrow before the current line.

buffer

Buffer in which to place the source listing.

buflen

Length of buffer.

pieces

Set to nonzero if not all the source could be placed into the given buffer.

PRINT_BACKTRACE Procedure

This procedure prints a backtrace listing of the current execution stack. This should only be called if a program is currently running.

There are two overloaded PRINT_BACKTRACE procedures.

Syntax

DBMS_DEBUG.PRINT_BACKTRACE (
listing IN OUT VARCHAR2);

Parameters

Table 10-13 PRINT_BACKTRACE Procedure Parameters

Parameter

Description

listing

A formatted character buffer with embedded newlines.

Syntax

DBMS_DEBUG.PRINT_BACKTRACE (
backtrace OUT backtrace_table);

Parameters

Table 10-14 PRINT_BACKTRACE Procedure Parameters

Parameter

Description

backtrace

1-based indexed table of backtrace entries. The currently-running procedure is the last entry in the table (that is, the frame numbering is the same as that used by GET_VALUE). Entry 1 is the oldest procedure on the stack.

CONTINUE Function

This function passes the given breakflags (a mask of the events that are of interest) to Probe in the target process. It tells Probe to continue execution of the target process, and it waits until the target process runs to completion or signals an event.

Syntax

Parameters

Table 10-17 SET_BREAKPOINT Function Parameters

Parameter

Description

program

Information about the program unit in which the breakpoint is to be set. (In version 2.1 and later, the namespace, name, owner, and dblink may be set to NULL, in which case the breakpoint is placed in the currently-running program unit.)

line#

Line at which the breakpoint is to be set.

breakpoint#

On successful completion, contains the unique breakpoint number by which to refer to the breakpoint.

fuzzy

Only applicable if there is no executable code at the specified line:

0 means return error_illegal_line.

1 means search forward for an adjacent line at which to place the breakpoint.

-1 means search backward for an adjacent line at which to place the breakpoint.

Parameters

Table 10-33 SET_VALUE Function Parameters

An assignment statement (which must be legal PL/SQL) to run in order to set the value. For example, 'x := 3;'.

Only scalar values are supported in this release. The right side of the assignment statement must be a scalar.

Table 10-34 SET_VALUE Function Returns

Return

Description

error_no_such_object

Either:

- Package does not exist.

- Package is not instantiated.

- User does not have privileges to debug the package.

- Object does not exist in the package.

In some cases, the PL/SQL compiler uses temporaries to access package variables, and Probe does not guarantee to update such temporaries. It is possible, although unlikely, that modification to a package variable using SET_VALUE might not take effect for a line or two.

DETACH_SESSION Procedure

This procedure stops debugging the target program. This procedure may be called at any time, but it does not notify the target session that the debug session is detaching itself, and it does not abort execution of the target session. Therefore, care should be taken to ensure that the target session does not hang itself.

Syntax

DBMS_DEBUG.DETACH_SESSION;

GET_RUNTIME_INFO Function

This function returns information about the current program. It is only needed if the info_requested parameter to SYNCHRONIZE or CONTINUE was set to 0.

Parameters

Table 10-36 GET_INDEXES Function Parameters

Number of frame in which the variable or parameter resides; NULL for a package variable.

handle

Package description, if object is a package variable.

entries

1-based table of the indexes. If non-NULL, then entries(1) contains the first index of the table, entries(2) contains the second index, and so on.

Returns

Table 10-37 GET_INDEXES Function Returns

Return

Description

error_no_such_object

Either:

- The package does not exist.

- The package is not instantiated.

- The user does not have privileges to debug the package.

- The object does not exist in the package.

EXECUTE Procedure

This procedure executes SQL or PL/SQL code in the target session. The target session is assumed to be waiting at a breakpoint (or other event). The call to DBMS_DEBUG.EXECUTE occurs in the debug session, which then asks the target session to execute the code.

Syntax

DBMS_DEBUG.EXECUTE (
what IN VARCHAR2,
frame# IN BINARY_INTEGER,
bind_results IN BINARY_INTEGER,
results IN OUT NOCOPY dbms_debug_vc2coll,
errm IN OUT NOCOPY VARCHAR2);

Parameters

Table 10-38 EXECUTE Procedure Parameters

Parameter

Description

what

SQL or PL/SQL source to execute.

frame#

The context in which to execute the code. Only -1 (global context) is supported at this time.

bind_results

Whether the source wants to bind to results in order to return values from the target session.

PRINT_INSTANTIATIONS Procedure

This procedure returns a list of the packages that have been instantiated in the current session.

Syntax

DBMS_DEBUG.PRINT_INSTANTIATIONS (
pkgs IN OUT NOCOPY backtrace_table,
flags IN BINARY_INTEGER);

Parameters

Table 10-39 PRINT_INSTANTIATIONS Procedure Parameters

Parameter

Description

pkgs (OUT)

The instantiated packages

flags

Bitmask of options:

1 - show specs

2 - show bodies

4 - show local instantiations

8 - show remote instantiations (NYI)

16 - do a fast job. The routine does not test whether debug information exists or whether the libunit is shrink-wrapped.

Exceptions

no_target_program - target session is not currently executing

Usage Notes

On return, pkgs contains a program_info for each instantiation. The valid fields are: Namespace, Name, Owner, and LibunitType.

In addition, Line# contains a bitmask of:

1 - the libunit contains debug info

2 - the libunit is shrink-wrapped

TARGET_PROGRAM_RUNNING Procedure

This procedure returns TRUE if the target session is currently executing a stored procedure, or FALSE if it is not.

Syntax

FUNCTION target_program_running RETURN BOOLEAN;

PING Procedure

This procedure pings the target session, to prevent it from timing out. Use this procedure when execution is suspended in the target session, for example at a breakpoint.

If the timeout_behavior is set to retry_on_timeout then this procedure is not necessary.

Syntax

DBMS_DEBUG.PING;

Exceptions

Oracle will display the no_target_program exception if there is no target program or if the target session is not currently waiting for input from the debug session.

Timeout Options

Timeout options for the target session are registered with the target session by calling set_timeout_behavior.

retry_on_timeout - Retry. Timeout has no effect. This is like setting the timeout to an infinitely large value.

continue_on_timeout - Continue execution, using same event flags.

nodebug_on_timeout - Turn debug-mode OFF (in other words, call debug_off) and then continue execution. No more events will be generated by this target session unless it is re-initialized by calling debug_on.

abort_on_timeout - Continue execution, using the abort_execution flag, which should cause the program to abort immediately. The session remains in debug-mode.

retry_on_timeout CONSTANT BINARY_INTEGER:= 0;

continue_on_timeout CONSTANT BINARY_INTEGER:= 1;

nodebug_on_timeout CONSTANT BINARY_INTEGER:= 2;

abort_on_timeout CONSTANT BINARY_INTEGER:= 3;

SET_TIMEOUT_BEHAVIOR Procedure

This procedure tells Probe what to do with the target session when a timeout occurs. This call is made in the target session.

Syntax

DBMS_DEBUG.SET_TIMEOUT_BEHAVIOR (
behavior IN PLS_INTEGER);

Parameters

Table 10-40 SET_TIMEOUT_BEHAVIOR Procedure Parameters

Parameter

Description

behavior - One of the following:

retry_on_timeout

Retry. Timeout has no effect. This is like setting the timeout to an infinitely large value.

continue_on_timeout

Continue execution, using same event flags.

nodebug_on_timeout

Turn debug-mode OFF (in other words, call debug_off) and continue execution. No more events will be generated by this target session unless it is re-initialized by calling debug_on.

abort_on_timeout

Continue execution, using the abort_execution flag, which should cause the program to abort immediately. The session remains in debug-mode.

Exceptions

unimplemented - the requested behavior is not recognized

Usage Notes

The default behavior (if this procedure is not called) is continue_on_timeout, since it allows a debugger client to reestablish control (at the next event) but does not cause the target session to hang indefinitely.

GET_TIMEOUT_BEHAVIOR Function

This procedure returns the current timeout behavior. This call is made in the target session.

Syntax

DBMS_DEBUG.GET_TIMEOUT_BEHAVIOR (
RETURN BINARY_INTEGER;

Information Flags

info_getOerInfoCONSTANT PLS_INTEGER:= 32;

Reasons

reason_oer_breakpoint CONSTANT BINARY_INTEGER:= 26;

RUNTIME_INFO

Runtime_info gives context information about the running program.

Probe v2.4:

Added OER. It gets set if info_getOerInfo is set. The OER is a positive number. It can be translated into SQLCODE by translating 1403 to 100, 6510 to 1, and negating any other value.

TYPE runtime_info IS RECORD
(
Line# BINARY_INTEGER, (duplicate of program.line#)
Terminated BINARY_INTEGER, has the program terminated?
Breakpoint BINARY_INTEGER, breakpoint number
StackDepth BINARY_INTEGER, number of frames on the stack
InterpreterDepth BINARY_INTEGER, <reserved field>
Reason BINARY_INTEGER, reason for suspension
Program program_info, source location
Following fields were added in Probe v2.4 oer PLS_INTEGER OER
(exception), if any
);

oer_table

Used by show_breakpoints

TYPE oer_table IS TABLE OF BINARY_INTEGER INDEX BY BINARY_INTEGER;

- SET_OER_BREAKPOINT

Set a breakpoint on an OER. The breakpoint persists for the session (or until deleted), as with code breakpoints.

Parameters

Table 10-41

Parameter

Description

oer

The OER (a 4-byte positive number).

Returns

success

Usage Notes

Less functionality is supported on OER breakpoints than on code breakpoints. In particular, note that:

No "breakpoint number" is returned - the number of the OER is used instead. Thus it is impossible to set duplicate breakpoints on a given OER (it is a no-op).

It is not possible to disable an OER breakpoint (although clients are free to simulate this by deleting it).