金仓数据库 KingbaseES 插件参考手册（23. dbms_utility）

23. dbms_utility

23.1. 插件dbms_utility简介

插件dbms_utility是KingbaseES 的一个扩展插件。插件dbms_utility功能是提供dbms_utility系统包。

dbms_utility系统包提供一些具有通用功能的子程序，如查看错误堆栈、查看时间等。

• 插件名为 dbms_utility

• 插件版本 V1.0

23.2. 插件dbms_utility加载方式

该插件为初始化数据库实例时默认创建。

23.3. 插件dbms_utility的参数配置

dbms_utility扩展插件无需配置任何参数。

23.4. 插件dbms_utility使用方法

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

23.4.1. FORMAT_CALL_STACK 函数

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

语法

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

注意

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

使用说明

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

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

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

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

**示例 1**

调用format_call_stack子程序无参数**示例**。

\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**

调用format_call_stack子程序传入'o'参数的**示例**。

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

CALL checkHexCallStack();

                         checkhexcallstack
--------------------------------------------------------------------
 ----- PL/SQL Call Stack -----                                     +
   object   line    object                                         +
   handle   number  name                                           +
     38ef      22   package body sys.dbms_utility.format_call_stack+
     4004       4   function public.checkhexcallstack
(1 row)

**示例 3**

调用format_call_stack子程序传入'p'参数的**示例**。

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

CALL checkIntCallStack();

                         checkintcallstack
--------------------------------------------------------------------
                                                                   +
    14575      22   package body sys.dbms_utility.format_call_stack+
    16389       4   function public.checkintcallstack
(1 row)

**示例 4**

调用format_call_stack子程序传入's'参数的**示例**。

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

call checkIntUnpaddedCallStack();

        checkintunpaddedcallstack
--------------------------------------------
                                           +
14575,22,sys.dbms_utility.format_call_stack+
16390,4,public.checkintunpaddedcallstack
(1 row)

23.4.2. FORMAT_ERROR_BACKTRACE 函数

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

语法

DBMS_UTILITY.FORMAT_ERROR_BACKTRACE() RETURN TEXT;

示例

format_error_backtrace函数在异常时使用，如下所示。

set serverout on
\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

23.4.3. FORMAT_ERROR_STACK 函数

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

语法

DBMS_UTILITY.FORMAT_ERROR_STACK() RETURN TEXT;

示例

见 FORMAT_ERROR_BACKTRACE 函数 。

23.4.4. GET_TIME 函数

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

语法

DBMS_UTILITY.GET_TIME() RETURN NUMBER;

使用说明

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

示例

get_time函数可用于计算语句运行时间，如下所示。

\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.

23.4.5. GET_HASH_VALUE 函数

对于指定的字符串，返回范围在[base, base+hase_size-1]的散列值。

语法

DBMS_UTILITY.GET_HASH_VALUE(
              NAME VARCHAR2,
              BASE NUMBER,
              HASH_SIZE NUMBER
              )RETURN NUMBER;

参数说明

返回值

基于输入字符串的哈希值。

异常说明

• BASE参数为NULL，则报错"bad argument"。

• HASH_SIZE参数为NULL，则报错"bad argument"。

• HASH_SIZE为0时，则报错"bad argument"。

使用说明

• BASE可为负值。

• 返回HASH值的最小值为BASE；返回HASH值的最大值BASH+HASH_SIZE-1。例如，若要获取哈希值介于1000和3047之间的字符串的哈希值，请使用1000作为基值，使用2048作为HASH表大小。

• NAME 为NULL或空字符串，若其他参数正常，则返回BASE值。

• 若HASH_SIZE为负值则返回的哈希值不在哈希范围内，哈希值可能为正，也可能为负。

示例

select DBMS_UTILITY.GET_HASH_VALUE('hello world',1,100) from dual;

get_hash_value
----------------
             61
(1 row)

23.5. 插件dbms_utility卸载方法

无法卸载。

23.6. 插件dbms_utility升级方法

若该插件有升级版本则通过 alter extension 来升级插件。

示例，由 1.0 升级到 1.1

ALTER EXTENSION dbms_utility UPDATE TO '1.1';