19.6.2 Tracing Execution of Your Code

Earlier versions of Oracle offered some PL/SQL trace capabilities, but Oracle8i provides an API that allows you to easily specify and control the tracing of the execution of PL/SQL procedures, functions, and exceptions. The DBMS_TRACE built-in package provides programs to start and stop PL/SQL tracing in a session. When tracing is turned on, the engine collects data as the program executes. The data is then written out to the Oracle Server trace file.

The PL/SQL trace facility provides a trace file that shows you the specific steps executed by your code. The DBMS_PROFILER package (described earlier in this chapter) offers a much more comprehensive analysis of your application, including timing information and counts of the number of times a specific line was executed.

19.6.2.1 Installing dbms_trace

This package may not have been installed automatically with the rest of the built-in packages. To determine whether DBMS_TRACE is present, connect to SYS (or another account with SYSDBA privileges) and execute this command:

BEGIN DBMS_TRACE.CLEAR_PLSQL_TRACE; END;

If you see this error:

PLS-00201: identifier 'DBMS_TRACE.CLEAR_PLSQL_TRACE'

must be declared

then you must install the package. To do this, remain connected as SYS (or another account with SYSDBA privileges) and run the following files in the order specified:

$ORACLE_HOME/rdbms/admin/dbmspbt.sql

$ORACLE_HOME/rdbms/admin/prvtpbt.plb

19.6.2.2 Dbms_trace programs

The following programs are available in the DBMS_TRACE package:

SET_PLSQL_TRACE

Starts PL/SQL tracing in the current session

CLEAR_PLSQL_TRACE

Stops the dumping of trace data for that session

PLSQL_TRACE_VERSION

Gets the major and minor version numbers of the DBMS_TRACE package

To trace execution of your PL/SQL code, you must first start the trace with a call to:

DBMS_TRACE.SET_PLSQL_TRACE (trace_level INTEGER);

in your current session, where trace_level is one of the following values:

• Constants that determine which elements of your PL/SQL program will be traced:

• DBMS_TRACE.trace_all_calls constant INTEGER := 1;

• DBMS_TRACE.trace_enabled_calls constant INTEGER := 2;

• DBMS_TRACE.trace_all_exceptions constant INTEGER := 4;

• DBMS_TRACE.trace_enabled_exceptions constant INTEGER := 8;

• DBMS_TRACE.trace_all_sql constant INTEGER := 32;

• DBMS_TRACE.trace_enabled_sql constant INTEGER := 64;

• DBMS_TRACE.trace_all_lines constant INTEGER := 128;

DBMS_TRACE.trace_enabled_lines constant INTEGER := 256;

• Constants that control the tracing process:

• DBMS_TRACE.trace_stop constant INTEGER := 16384;

• DBMS_TRACE.trace_pause constant INTEGER := 4096;

• DBMS_TRACE.trace_resume constant INTEGER := 8192;

DBMS_TRACE.trace_limit constant INTEGER := 16;

By combining the DBMS_TRACE constants, you can enable tracing of multiple PL/SQL language features simultaneously. Note that the constants that control the tracing behavior (such as DBMS_TRACE.trace_pause) should not be used in combination with the other constants (such as DBMS_TRACE.trace_enabled_calls).

To turn on tracing from all programs executed in your session, issue this call:

DBMS_TRACE.SET_PLSQL_TRACE (DBMS_TRACE.trace_all_calls);

To turn on tracing for all exceptions raised during the session, issue this call:

DBMS_TRACE.SET_PLSQL_TRACE (DBMS_TRACE.trace_all_exceptions);

You then run your code. When you are done, you stop the trace session by calling:

DBMS_TRACE.CLEAR_PLSQL_TRACE;

You can then examine the contents of the trace file. The names of these files are generated by Oracle; you will usually look at the modification dates to figure out which file to examine. The location of the trace files is discussed in the later section Section 19.6.2.5.

Note that you cannot use PL/SQL tracing with the multithreaded server (MTS).