NAME

Oracle::Debug - A Perl (perldb-like) interface to the Oracle DBMS_DEBUG package for debugging PL/SQL programs.

SYNOPSIS

        ./oradb

ABSTRACT

A perl-debugger-like interface to the Oracle DBMS_DEBUG package for debugging PL/SQL programs.

The initial impetus for creating this was to get a command-line interface, similar in instruction set and feel to the perl debugger. For this reason, it may be beneficial for a user of this module, or at least the intended oradb interface, to be familiar with the perl debugger first.

DESCRIPTION

There are really 2 parts to this exersize:

DB

The current Oracle chunk is a package which can be used directly to debug PL/SQL without involving perl at all, but which has similar, but very limited, commands to the perl debugger.

Please see the packages/header.sql file for credits for the original db PL/SQL.

Developed against Probe version 2.4

oradb

The Perl chunk implements a perl-debugger-like interface to the Oracle debugger itself, partially via the DB library referenced above.

In both cases much more conveniently from the command line, than the vanilla Oracle packages themselves. In fairness DBMS_DEBUG is probably designed to be used from a GUI of some sort, but this module focuses on it from a command line usage.

NOTES

Ignore any methods which are prefixed with an underscore (_)

We use a special oradb_table for our own purposes.

Set Oracle_Debug=1 for debugging information.

METHODS

new

Create a new Oracle::Debug object

        my $o_debug = Oracle::Debug->new(\%dbconnectdata);

_prime

Prime the object and connect to the db

Also ensure we are able to talk to Probe

        $o_debug->_prime;

dbh

Return the database handle

        my $dbh = $o_debug->dbh;

_connect

Connect to the database

getarow

Get a row

        my ($res) = $o_debug->getarow($sql);

getahash

Get a list of hashes

        my ($res) = $o_debug->getahash($sql);

help

Print the help listings where levl is one of:

        h    (simple)

        h h  (detail)
        
        h b  (help for break command etc.)

        $o_oradb->help($levl);

preparse

Return the command via the shortest match possible

        my $command = $o_oradb->preparse($cmd); # (help|he)->h

parse

Parse the input command to the appropriate method

        $o_oradb->parse($cmd, $input);

do

Wrapper for oradb->dbh->do() - internally we still use prepare and execute.

        $o_oradb->do($sql);

recompile

Recompile these procedure|function|package's for debugging

        $oradb->recompile('xsource');

synchronize

Synchronize the debug and target sessions

        $o_oradb->synchronize;

unitdata

Retrieve data for given unit - expects to recieve single record from db!

        %data = $o_oradb->unitdata('name'=>$name, 'type'=>$type, ...);

perl

Run a chunk of perl

        $o_oradb->perl($perl);

shell

Run a shell command

        $o_oradb->shell($shellcommand);

sql

Run a chunk of SQL (select only)

        $o_oradb->sql($sql);

_run

Run a chunk

        $o_oradb->_run($sql);

target

Run the target session

        $o_oradb->target;

start_target

Get the target session id(given) and stick it in our table (by process_id)

        my $dbid = $oradb->start_target($dbid);

        # should be autonomous transaction
        my $insert = qq#INSERT INTO $self->{_config}{table} 
           (created, debugpid, targetpid, sessionid, data) 
                VALUES (sysdate, $$, $$, '$dbid', 'xxx'
        )#;
        $x_res = $self->do($insert);

        $x_res = $self->do('COMMIT');

debugger

Run the debugger

        $o_debug->debugger;

start_debug

Start the debugger session

        my $i_res = $oradb->start_debug($db_session_id, $pid);

sync

Blocks debug session until we exec in target session

        my $i_res = $oradb->sync;

execute

Runs the given statement against the target session

        my $i_res = $oradb->execute($xsql);

break

Set a breakpoint

        my $i_res = $oradb->break("$i_line $procedurename");

continue

Continue execution until given breakpoints

        my $i_res = $oradb->continue;

next

Step over the next line

        my $i_res = $oradb->next;

step

Step into the next statement

        my $i_res = $oradb->step;

return

Return from the current scope

        my $i_res = $oradb->return;

runtime

Print runtime_info via dbms_output

        $oradb->runtime;

backtrace

Print backtrace from runtime info via dbms_output

        $o_oradb->backtrace();

list_source

Print source

        $oradb->list_source('xsource', [PROC|...]);

list_breakpoints

Print breakpoint info

        $oradb->list_breakpoints;

history

Display the command history

        print $o_oradb->history;        

rerun

Rerun a command from the history list

        $o_oradb->rerun($histno);

info

Info

        print $oradb->info;

context

Get and set context info

        my $s_res = $o_oradb->context($name);         # get

        my $s_res = $o_oradb->context($name, $value); # set

probe_version

Log the Probe version

        print $oradb->probe_version;

test

Call self_check, ping and is_running

        my $i_ok = $oradb->test();

self_check

Self->check

        my $i_ok = $oradb->self_check; # 9.2

ping

Ping the target process (gives an ORA-error if no target)

        my $i_ok = $oradb->ping; # 9.2

is_running

Check the target is still running - ???

        my $i_ok = $oradb->is_running; # 9.2

plsql_errstr

Get PL/SQL error string

        $o_debug->plsql_errstr;

put_msg

Put debug message info

        $o_debug->put_msg($msg);

get_msg

Get debug message info

        print $o_debug->get_msg;

value

Get and set the value of a variable, in a procedure, or in a package

        my $val = $o_oradb->value($name);

        my $val = $o_oradb->value($name, $value);

_get_val

Get the value of a variable

        my $val = $o_debug->_get_val($varname);

_set_val

Set the value of a variable

        my $val = $o_debug->_set_val($xset);

audit

Get auditing info

        my ($audsid) = $o_debug->audit;

_check

Return whether or not the given PLSQL target has a value of some sort

        my $i_ok = $o_oradb->_check('unit');

_unit

Get and set unit name for all consequent actions

        $o_oradb->_unit;        # get

        $o_oradb->_unit($name); # set

_type

Get and set type for all consequent actions

        $o_oradb->_type;        # get

        $o_oradb->_type($type); # set

_namespace

Get and set unit namespace for all consequent actions

        $o_oradb->_namespace;         # get

        $o_oradb->_namespace($space); # set

_owner

Get and set unit owner for all consequent actions

        $o_oradb->_owner;        # get

        $o_oradb->_owner($user); # set

feedback

Feedback handler (currently just prints to STDOUT)

        $o_debug->feedback("this");

log

Log handler (currently just prints to STDERR)

        $o_debug->log("this");

quit

Quit the debugger

        $o_oradb->quit;

error

Error handler

fatal

Fatal error handler

abort

Tell the target session to abort the currently running program

        $o_debug->abort;

detach

Tell the target session to detach itself

        $o_debug->detach;

SEE ALSO

DBD::Oracle

perldebug

AUTHOR

Richard Foley, <Oracle_Debug@rfi.net>

COPYRIGHT AND LICENSE

Copyright 2003 by Richard Foley

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.