#

| Chapter 5 PL/Vision Package Specifications |

## 5.28 PLVtrc: Trace Facility

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

### 5.28.1 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`.

### 5.28.2 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.

### 5.28.4 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.

### 5.28.5 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.

### 5.28.6 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`.

### 5.28.7 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.

### 5.28.8 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.

5.27 PLVtmr: Program Performance Analyzer |  | 5.29 PLVvu: Code and Error Viewing

Copyright (c) 2000 O'Reilly & Associates. All rights reserved.