247 UTL_CALL_STACK

Overview

The UTL_CALL_STACK package provides an interface for PL/SQL programmers to obtain information about currently executing programs including the subprogram name from dynamic and lexical stacks and the depths of those stacks. Individual functions return subprogram names, unit names, owner names, edition names, and line numbers for given dynamic depths. More functions return error stack information. Such information can be used to create more revealing error logs and application execution traces.

Dynamic Depth

The dynamic depth of an executing instance of a PL/SQL subprogram is defined recursively.

• The dynamic depth of the currently executing subprogram instance is one.

• Otherwise, the dynamic depth of the subprogram instance is one more than the dynamic depth of the subprogram it invoked.

• If there is a SQL, Java, or other non-PL/SQL context that invoked or was invoked by an executing subprogram, it occupies a level on the call stack as if it were a subprogram.

In the case of a call stack in which A calls B, which calls C, which calls D, which calls E, which calls F, which calls E, this stack can be written as a line with the dynamic depths underneath:

A B C D E F E
7 6 5 4 3 2 1

Lexical Depth

The lexical depth of a PL/SQL subprogram is defined recursively.

• The lexical depth of a unit, an anonymous block, trigger, or ADT is one (1).

• The lexical depth of a subprogram defined within another object is one plus the lexical depth of that object.

Blocks do not affect lexical depth.

Error Depth

The error depth is the number of errors on the error stack.

For example, consider the following anonymous block.

BEGIN
  BEGIN
    ... (1)
    raise zero_divide;
  EXCEPTION
    when others then
      raise no_data_found;
  END;
EXCEPTION
  WHEN others THEN
    ... (2)
END;

The error depth at (1) is zero and at (2) is two.

Backtrace

The backtrace is a trace from where the exception was thrown to where the backtrace was examined.

Consider a call stack in which A calls B which calls C and C raises an exception. If the backtrace was examined in C, the backtrace would have one unit, C, and the backtrace depth would be one. If it was examined in A, it would have three units, A, B and C, and backtrace depth would be three.

The depth of a backtrace is zero in the absence of an exception.

Security Model

EXECUTE on UTL_CALL_STACK is granted to PUBLIC.

The UTL_CALL_STACK package does not show wrapped program units. For example, consider a call stack in which program unit A calls B, which calls C, and in turn calls UTL_CALL_STACK to determine the subprogram list. If program unit B is wrapped, then the subprogram list onlys shows program unit C.

Operational Notes

Compiler optimizations can change lexical, dynamic and backtrace depth.

UTL_CALL_STACK is not supported past RPC boundaries. For example, if A calls remote procedure B, B will not be able to obtain information about A using UTL_CALL_STACK.

Lexical unit information is available through the PL/SQL conditional compilation feature and is therefore not exposed through UTL_CALL_STACK.

Exceptions

The following table lists the exceptions raised by UTL_CALL_STACK.

UNIT_QUALIFIED_NAME

TYPE UNIT_QUALIFIED_NAME IS VARRAY(256) OF VARCHAR2(32767);

This data structure is a varray whose individual elements are, in order, the unit name, any lexical parents of the subprogram, and the subprogram name.

Example

Consider the following contrived PL/SQL procedure:

PROCEDURE topLevel IS
  FUNCTION localFunction(...) RETURNS VARCHAR2 IS
    FUNCTION innerFunction(...) RETURNS VARCHAR2 IS
      BEGIN
        DECLARE
          localVar PLS_INTEGER;
        BEGIN
          ... (1)
        END;
      END;
  BEGIN
    ...
  END; 

The unit qualified name at (1) would be

["topLevel", "localFunction", "innerFunction"] 

If the unit were an anonymous block, the unit name would be "__anonymous_block"

BACKTRACE_DEPTH Function

This function returns the number of backtrace items in the backtrace.

UTL_CALL_STACK.BACKTRACE_DEPTH 
 RETURN PLS_INTEGER;

BACKTRACE_LINE Function

This function returns the line number of the unit at the specified backtrace depth.

UTL_CALL_STACK.BACKTRACE_LINE (
   backtrace_depth   IN   PLS_INTEGER)
 RETURN PLS_INTEGER;

BACKTRACE_UNIT Function

This function returns the name of the unit at the specified backtrace depth.

UTL_CALL_STACK.BACKTRACE_UNIT (
   backtrace_depth   IN   PLS_INTEGER)
 RETURN VARCHAR2;

CURRENT_EDITION Function

This function returns the current edition name of the unit of the subprogram at the specified dynamic depth.

UTL_CALL_STACK.CURRENT_EDITION (
   dynamic_depth    IN    PLS_INTEGER) 
 RETURN VARCHAR2;

CONCATENATE_SUBPROGRAM Function

This function returns a concatenated form of a unit-qualified name.

UTL_CALL_STACK.CONCATENATE_SUBPROGRAM (
   qualified_name    IN    UNIT_QUALIFIED_NAME) 
 RETURN VARCHAR2;

DYNAMIC_DEPTH Function

This function returns the number of subprograms on the call stack.

UTL_CALL_STACK.DYNAMIC_DEPTH
 RETURN PLS_INTEGER;

ERROR_DEPTH Function

This function returns the number of errors on the error stack.

UTL_CALL_STACK.ERROR_DEPTH
 RETURN PLS_INTEGER;

ERROR_MSG Function

This function returns the error message of the error at the specified error depth.

UTL_CALL_STACK.ERROR_MSG (
   error_depth    IN    PLS_INTEGER) 
 RETURN VARCHAR2;

ERROR_NUMBER Function

This function returns the error number of the error at the specified error depth.

UTL_CALL_STACK.ERROR_NUMBER (
   error_depth    IN    PLS_INTEGER) 
 RETURN PLS_INTEGER;

LEXICAL_DEPTH Function

This function returns the lexical nesting level of the subprogram at the specified dynamic depth.

UTL_CALL_STACK.LEXICAL_DEPTH (
   dynamic_depth    IN    PLS_INTEGER) 
 RETURN PLS_INTEGER;

OWNER Function

This function returns the owner name of the unit of the subprogram at the specified dynamic depth.

UTL_CALL_STACK.OWNER (
   dynamic_depth    IN    PLS_INTEGER) 
 RETURN VARCHAR2;

UNIT_LINE Function

This function returns the line number of the unit of the subprogram at the specified dynamic depth.

UTL_CALL_STACK.UNIT_LINE (
   dynamic_depth    IN    PLS_INTEGER) 
 RETURN PLS_INTEGER;

SUBPROGRAM Function

This function returns the unit-qualified name of the subprogram at the specified dynamic depth.

UTL_CALL_STACK.SUBPROGRAM (
   dynamic_depth    IN    PLS_INTEGER) 
 RETURN UNIT_QUALIFIED_NAME;