PLVtrc: Trace Facility

The PLVtrc (PL/Vision TRaCe) package provides a generic trace facility for PL/SQL applications for use in debugging. See for details.

Package constants

• c_top_pos CONSTANT INTEGER := 0;
• Name of position of top module in the call stack. The argument you would pass to the PLVtrc.module function to retrieve the topmost program in the execution call stack.
• c_last_pos CONSTANT INTEGER := 2;
• Name of position of most recent module in call stack. The argument you would pass to the PLVtrc.module function to retrieve the last program executed before the call to PLVtrc.module.

Controlling trace activity

• PROCEDURE turn_on;
• Turns on the trace, enabling output from calls to the programs described below.
• PROCEDURE turn_off;
• Turns off the trace.
• FUNCTION tracing RETURN BOOLEAN;
• Returns TRUE if the trace is active.

5.28.3 Writing to the PL/Vision log

• PROCEDURE log;
• Turns on logging of trace message to the PL/Vision log (see the PLVlog package), in addition to displaying the trace.
• PROCEDURE nolog;
• Turns off logging (the default).
• FUNCTION logging RETURN BOOLEAN;
• Returns TRUE if logging of trace messages is currently turned on.

Displaying current module

• PROCEDURE dispmod;
• Turns on display of current module when showing the trace message.
• PROCEDURE nodispmod;
• Turns off display of current module (the default).
• FUNCTION displaying_module RETURN BOOLEAN;
• Returns TRUE if PLVtrc is displaying the current module.

Accessing the PL/SQL call stack

• FUNCTION ps_callstack RETURN VARCHAR2;
• Returns the string generated by a call to DBMS_UTILITY.FORMAT_CALL_STACK.
• FUNCTION ps_module (pos_in IN INTEGER := c_last_pos)
• RETURN VARCHAR2;
• Returns the nth module (specified by the user) in the PL/SQL execution call stack.

Tracing PL/SQL code execution

• PROCEDURE startup
• (module_in IN VARCHAR2, string_in IN VARCHAR2 := NULL);
• Executes the first line of your programs. Maintains a PLVtrc execution stack, which is then available to other PL/Vision packages.
• PROCEDURE terminate (string_in IN VARCHAR2 := NULL);
• Executes as the last line of your programs. Removes the current program from the PLVtrc execution stack.
• FUNCTION currmod RETURN VARCHAR2;
• Returns the name of the current module as set by calls to the procedure PLVtrc.startup.
• FUNCTION prevmod RETURN VARCHAR2;
• Returns the name of the previous module as set by calls to the procedure PLVtrc.terminate.

Displaying an activity trace

The show procedure is heavily overloaded for different datatypes and combinations of datatypes, along the lines of the p.l procedure. In all cases, the information you pass to show is, well, shown if you have turned on the PLVtrc facility.

• PROCEDURE show (stg1 IN VARCHAR2);
• PROCEDURE show (bool1 IN BOOLEAN);
• PROCEDURE show (num1 IN NUMBER);
• PROCEDURE show
• (date1 IN DATE, mask_in IN VARCHAR2 := PLV.datemask);
• Single value shows.
• PROCEDURE show (stg1 IN VARCHAR2, num1 IN NUMBER);
• PROCEDURE show (stg1 IN VARCHAR2, bool1 IN BOOLEAN);
• PROCEDURE show
• (stg1 IN VARCHAR2, date1 IN DATE,
• mask_in IN VARCHAR2 := PLV.datemask);
• Two-value combination shows.
• PROCEDURE show (stg1 IN VARCHAR2, num1 IN NUMBER, num2 IN NUMBER);
• PROCEDURE show
• (stg1 IN VARCHAR2, num1 IN NUMBER, bool1 IN BOOLEAN);
• PROCEDURE show
• (stg1 IN VARCHAR2, num1 IN NUMBER, date1 IN DATE,
• mask_in IN VARCHAR2 := PLV.datemask);
• Three-value combination shows.
• PROCEDURE action
• (string_in IN VARCHAR2 := NULL,
• counter_in IN INTEGER := NULL,
• prefix_in IN VARCHAR2 := NULL);
• Displays a trace of a particular action; you provide a context, numeric code, and string for the action.

Accessing the PLVtrc execution call stack (ECS)

• PROCEDURE showecs;
• Displays the PLVtrc-maintained execution call stack.
• PROCEDURE clearecs;
• Clears the PLVtrc execution call stack.
• FUNCTION ecs_string RETURN VARCHAR2;
• Returns a string which contains the current PLVtrc execution call stack (ecs), with each module separated by a newline character.
• FUNCTION module (pos_in IN INTEGER := c_top_pos) RETURN VARCHAR2;
• Returns the nth module in the PLVtrc execution call stack.