金仓数据库 KingbaseES 插件DBMS_UTILITY

1. DBMS_UTILITY系统包概述

DBMS_UTILITY 系统包提供一些具有通用功能的子程序。
DBMS_UTILITY 系统包不支持PG模式。

2. DBMS_UTILITY 系统包子程序

DBMS_UTILITY 系统包包含的子程序及简介如下表所示：
表 1  DBMS_UTILITY 包子程序

子程序	简介
FORMAT_CALL_STACK 函数	返回当前的调用堆栈。
FORMAT_ERROR_STACK 函数	返回当前的错误堆栈。
FORMAT_ERROR_BACKTRACE 函数	返回当前的错误回溯信息。
GET_TIME 函数	返回一个时间戳。

2.1. FORMAT_CALL_STACK 函数
该函数可以返回当前的调用堆栈信息，包括调用对象的地址，调用的行号和调用对象的名称， 它可以用在函数、存储过程或者触发器等 PL/SQL 对象中，用于帮助调试 PL/SQL 程序。
语法：

DBMS_UTILITY.FORMAT_CALL_STACK() RETURN TEXT;
DBMS_UTILITY.FORMAT_CALL_STACK(FORMAT TEXT) RETURN TEXT;

Note

目前调用对象的地址为函数或过程的oid值，如果是内建函数或过程则为对应包的oid值。

使用说明：

FORMAT: 指定调用堆栈信息的显示模式，分别有 'o', 'p', 's' 三种模式。默认使用模式为'p'模式，输出8位有效长度的十进制数输出对象地址信息。

• 其中 'o' 参数将按照 '%8x%8d%s' 格式打印对象地址，调用行号，对象名称，如示例 2 所示。
• 其中 'p' 参数将按照 '%8d%8d%s' 格式打印对象地址，调用行号，对象名称，如示例 3 所示。
• 其中 's' 参数将按照 '%d,%d,%s' 格式打印对象地址，调用行号，对象名称，如示例 4 所示。

示例 ：

\set SQLTERM /
CREATE OR REPLACE FUNCTION checkCallStack() RETURNS TEXT AS
  stack TEXT;
BEGIN
  SELECT dbms_utility.format_call_stack() INTO stack ;
  RETURN stack;
END;
/
\set SQLTERM ;

call checkCallStack();

                           checkcallstack
--------------------------------------------------------------------
----- PL/SQL Call Stack -----                                     +
   object   line    object                                         +
   handle   number  name                                           +
    14575      30   package body sys.dbms_utility.format_call_stack+
    16387       4   function public.checkcallstack
(1 row)

2.2. FORMAT_ERROR_STACK 函数
该函数用于返回当前程序发生异常时的错误堆栈，若程序未发生异常，则返回 NULL。
语法：

DBMS_UTILITY.FORMAT_ERROR_STACK() RETURN TEXT;

2.3. FORMAT_ERROR_BACKTRACE 函数
该函数用于返回当前程序发生异常时的错误回溯堆栈，若程序未发生异常，则返回 NULL。
语法：

DBMS_UTILITY.FORMAT_ERROR_BACKTRACE() RETURN TEXT;

示例：

\set SQLTERM /
CREATE OR REPLACE PROCEDURE p01() AS
  i INT := 0;
BEGIN
  i = i/0;
END;
/
\set SQLTERM ;

\set SQLTERM /
CREATE OR REPLACE PROCEDURE p02() AS
  detail TEXT;
  stack TEXT;
BEGIN
  p01();
EXCEPTION
  WHEN DIVISION_BY_ZERO THEN
    detail = dbms_utility.format_error_stack();
    stack = dbms_utility.format_error_backtrace();
    DBMS_OUTPUT.PUT_LINE('FORMAT_ERROR_STACK IS:');
    DBMS_OUTPUT.PUT_LINE(detail);
    DBMS_OUTPUT.PUT_LINE('FORMAT_ERROR_BACKTRACE IS:');
    DBMS_OUTPUT.PUT_LINE(stack);
END;
/
\set SQLTERM ;

CALL p02();

FORMAT_ERROR_STACK IS:
division by zero
at "public.p01", line 4
FORMAT_ERROR_BACKTRACE IS:
at "public.p01", line 4
at "public.p02", line 5

2.4. GET_TIME 函数
该函数用于返回一个时间戳，该时间戳不是标准的系统时间戳，单位为厘秒（百分之一秒）。通常在 PL/SQL 程序开始 和结束时各调用一次该函数，然后用后一个数字减去前一个数字，以确定当前程序的执行耗时。
语法：

DBMS_UTILITY.GET_TIME() RETURN NUMBER;

使用说明：

函数的返回值在 -2147483648 到 2147483647 之间，具体数值取决于机器和系统。调用该函数时，应用程序 需要考虑到返回值的符号。例如，两次调用皆为负数，或者第一次调用为负数，第二次调用为正数等情况。

示例：

\set SQLTERM /
CREATE OR REPLACE PROCEDURE TestGetTime() AS
  t1  PLS_INTEGER;
  t2  PLS_INTEGER;
BEGIN
  t1 := dbms_utility.get_time();
  perform pg_sleep(3);
  t2 := dbms_utility.get_time();

  RAISE NOTICE 'sleeped: % sec.', (t2 - t1) / 100;
END;
/
\set SQLTERM ;

call TestGetTime();

NOTICE:  sleeped: 3 sec.