文档首页/ 云数据库 GaussDB/ 开发指南（分布式_3.x）/ 存储过程/ 高级包/ 二次封装接口(推荐)/ DBE_UTILITY

更新时间：2024-05-07 GMT+08:00

DBE_UTILITY

接口介绍

高级功能包DBE_UTILITY支持的所有接口请参见表1。

表1 DBE_UTILITY
接口名称	描述
DBE_UTILITY.FORMAT_ERROR_BACKTRACE	输出存储过程异常的调用堆栈。
DBE_UTILITY.FORMAT_ERROR_STACK	输出存储过程异常的具体信息。
DBE_UTILITY.FORMAT_CALL_STACK	输出存储过程的调用堆栈。
DBE_UTILITY.GET_TIME	输出当前时间，一般用于做差得到执行时长。
DBE_UTILITY.CANONICALIZE	用于给表名字符串做规范。
DBE_UTILITY.COMMA_TO_TABLE	将用逗号隔开的名字列表的字符串转换为PL/SQL表名列表。
DBE_UTILITY.DB_VERSION	返回数据库的版本号和兼容性版本号。
DBE_UTILITY.EXEC_DDL_STATEMENT	用于执行用户输入的DDL语句。
DBE_UTILITY.EXPAND_SQL_TEXT_PROC	用于展开SQL查询的视图。
DBE_UTILITY.GET_CPU_TIME	返回当前CPU处理时间的测量值。
DBE_UTILITY.GET_ENDIANNESS	用于获取数据库所在平台字节序的大小端信息。
DBE_UTILITY.GET_HASH_VALUE	返回一个给定字符串的hash值。
DBE_UTILITY.GET_SQL_HASH	输出一个给定字符串的hash值，该存储过程在不打开proc_outparam_override时使用。
DBE_UTILITY.IS_BIT_SET	用于检查参数n是否存在于r。
DBE_UTILITY.IS_CLUSTER_DATABASE	用于判断当前数据库是否在数据库集群模式下运行。
DBE_UTILITY.NAME_RESOLVE	解析给定的对象名称，包括同义词翻译和必要的授权检查。
DBE_UTILITY.NAME_TOKENIZE	用于解析a [. b [. c ]][@ dblink ]形式的名字。
DBE_UTILITY.OLD_CURRENT_SCHEMA	返回当前用户环境下的数据库模式名称。
DBE_UTILITY.OLD_CURRENT_USER	返回当前用户的名称。
DBE_UTILITY.TABLE_TO_COMMA	将PL/SQL中的表名转换为用逗号隔开的名字列表的字符串。
DBE_UTILITY.GET_SQL_HASH_FUNC	功能同DBE_UTILITY.GET_SQL_HASH，该函数在打开proc_outparam_override时使用。
DBE_UTILITY.EXPAND_SQL_TEXT	内部函数，不建议用户使用。
DBE_UTILITY.CANONICALIZE_RET	内部函数，不建议用户使用。
DBE_UTILITY.COMMA_TO_TABLE_FUN	内部函数，不建议用户使用。
DBE_UTILITY.COMPILE_SCHEMA	内部函数，不建议用户使用。
DBE_UTILITY.NAME_SEPARATE	内部函数，不建议用户使用。
DBE_UTILITY.NAME_TOKENIZE_FUNC	内部函数，不建议用户使用。
DBE_UTILITY.NAME_TOKENIZE_LOWER	内部函数，不建议用户使用。
DBE_UTILITY.NAME_TOKENIZE_LOWER_FUNC	内部函数，不建议用户使用。
DBE_UTILITY.PRIVILEGE_CHECK	内部函数，不建议用户使用。
DBE_UTILITY.SEARCH_CLASS_WITH_NSPOID_ONAME_TYPE	内部函数，不建议用户使用。
DBE_UTILITY.SEARCH_OBJECTS	内部函数，不建议用户使用。
DBE_UTILITY.SEARCH_OBJECTS_SYNONYM_FILL_SECHEMA	内部函数，不建议用户使用。
DBE_UTILITY.SEARCH_PROCEDURE_WITH_NSPOID_ONAME	内部函数，不建议用户使用。
DBE_UTILITY.SEARCH_SYNONM_WITH_NSPOID_ONAME	内部函数，不建议用户使用。
DBE_UTILITY.TABLE_TO_COMMA_FUNC	内部函数，不建议用户使用。
DBE_UTILITY.USER_NAME	内部函数，不建议用户使用。

DBE_UTILITY.FORMAT_ERROR_BACKTRACE
存储过程FORMAT_ERROR_BACKTRACE返回在执行过程中出现错误时，出现错误位置的调用堆栈。DBE_UTILITY.FORMAT_ERROR_BACKTRACE函数原型为：
1 2

DBE_UTILITY.FORMAT_ERROR_BACKTRACE() RETURN TEXT;

DBE_UTILITY.FORMAT_ERROR_STACK
存储过程FORMAT_ERROR_STACK返回在执行过程中出现错误时，出现错误位置的具体信息。DBE_UTILITY.FORMAT_ERROR_STACK函数原型为：
1 2

DBE_UTILITY.FORMAT_ERROR_STACK() RETURN TEXT;

DBE_UTILITY.FORMAT_CALL_STACK
存储过程FORMAT_CALL_STACK设置输出函数调用堆栈。DBE_UTILITY.FORMAT_CALL_STACK函数原型为：
1 2

DBE_UTILITY.FORMAT_CALL_STACK() RETURN TEXT;

DBE_UTILITY.GET_TIME
存储过程GET_TIME设置输出时间，通常用于做差，单独的返回值没有意义。DBE_UTILITY.GET_TIME函数原型为：
1 2

DBE_UTILITY.GET_TIME() RETURN BIGINT;

DBE_UTILITY.CANONICALIZE

存储过程CANONICALIZE用于给表名字符串做规范。该过程处理单个保留字或关键字，并删除单个标识符的空白，以便“table”成为TABLE。DBE_UTILITY.CANONICALIZE函数原型为：

     
          DBE_UTILITY.CANONICALIZE(
    name       IN   VARCHAR2,
    canon_name OUT  VARCHAR2,
    canon_len  IN   BINARY_INTEGER
);

表2 DBE_UTILITY.CANONICALIZE接口说明
参数名称	描述
name	待规范的字符串。
canon_name	规范好的字符串。
canon_len	要规范的字符串长度（以字节为单位）。若此参数的值小于待规范的字符串的实际长度（字节），则会以字节为粒度截断字符串。

DBE_UTILITY.COMMA_TO_TABLE

存储过程COMMA_TO_TABLE将用逗号隔开的名字列表的字符串转换为PL/SQL表名列表。DBE_UTILITY.COMMA_TO_TABLE函数原型为：

     
          DBE_UTILITY.COMMA_TO_TABLE ( 
    list   IN  VARCHAR2,
    tablen OUT BINARY_INTEGER,
    tab    OUT uncl_array
);

表3 DBE_UTILITY.COMMA_TO_TABLE接口说明
参数名称	描述
list	逗号隔开的名字列表字符串。
tablen	列表名字的个数。
tab	转换后的表名称列表。

DBE_UTILITY.DB_VERSION

存储过程DB_VERSION返回数据库的版本号和兼容性版本号。DBE_UTILITY.DB_VERSION函数原型为：

     
          DBE_UTILITY.DB_VERSION (
    version OUT VARCHAR2
);

表4 DBE_UTILITY.DB_VERSION接口说明
参数名称	描述
version	输出参数，表示内部的数据库软件版本信息，是一个字符串。

DBE_UTILITY.EXEC_DDL_STATEMENT

存储过程EXEC_DDL_STATEMENT用于执行用户输入的DDL语句。DBE_UTILITY.EXEC_DDL_STATEMENT函数原型为：

     
          DBE_UTILITY.EXEC_DDL_STATEMENT (
    parse_string IN VARCHAR2
);

表5 DBE_UTILITY.EXEC_DDL_STATEMENT接口说明
参数名称	描述
parse_string	需要执行的DDL语句。

DBE_UTILITY.EXPAND_SQL_TEXT_PROC

存储过程EXPAND_SQL_TEXT_PROC用于展开SQL查询的视图，会递归展开视图中的视图对象，一直展开显示到表。DBE_UTILITY.EXPAND_SQL_TEXT_PROC函数原型为：

     
          DBE_UTILITY.EXPAND_SQL_TEXT_PROC (
    input_sql_text  IN           CLOB,
    output_sql_text OUT NOCOPY CLOB
);

表6 DBE_UTILITY.EXPAND_SQL_TEXT_PROC接口说明
参数名称	描述
input_sql_text	输入的SQL文本。
output_sql_text	输出展开视图的SQL文本。

用户输入的input_sql_text参数中，SQL语句中的对象需要增加schema前缀，否则函数会报无法找到对象的错误。若设置set behavior_compat_options参数值为bind_procedure_searchpath，则无需强制指定schema前缀。

DBE_UTILITY.GET_CPU_TIME
存储过程GET_CPU_TIME返回当前CPU处理时间的测量值（以百分之一秒为单位）。DBE_UTILITY.GET_CPU_TIME函数原型为：
1 2

DBE_UTILITY.GET_CPU_TIME() RETURN NUMBER;

DBE_UTILITY.GET_ENDIANNESS
存储过程GET_ENDIANNESS用于获取数据库所在平台字节序的大小端信息。DBE_UTILITY. GET_ENDIANNESS函数原型为：
1 2

DBE_UTILITY.GET_ENDIANNESS RETURN INTEGER;

DBE_UTILITY.GET_HASH_VALUE

存储过程GET_HASH_VALUE返回一个给定字符串的hash值。DBE_UTILITY.GET_HASH_VALUE函数原型为：

     
          DBE_UTILITY.GET_HASH_VALUE(
    name      IN VARCHAR2(n),
    base      IN INTEGER,
    hash_size IN INTEGER)
RETURN INTEGER;

表7 DBE_UTILITY.GET_HASH_VALUE接口说明
参数名称	描述
name	待哈希转换的字符串。
base	返回哈希值的起始值。
hash_size	哈希映射到的哈希表的大小。

DBE_UTILITY.GET_SQL_HASH

存储过程GET_SQL_HASH通过MD5算法输出一个给定字符串的hash值。DBE_UTILITY.GET_SQL_HASH函数原型为：

     
          DBE_UTILITY.GET_SQL_HASH(
    name       IN  VARCHAR2,
    hash       OUT RAW,
    last4bytes OUT BIGINT
);

表8 DBE_UTILITY.GET_SQL_HASH接口说明
参数名称	描述
name	待哈希转换的字符串。
hash	完整的16进制MD5哈希值。
last4bytes	MD5哈希值的最后四字节，以无符号整数形式展现。

设置set behavior_compat_options为非proc_outparam_override参数后，请调用DBE_UTILITY.GET_SQL_HASH函数，如调用DBE_UTILITY.GET_SQL_HASH_FUNC则会发生赋值不成功。

DBE_UTILITY.IS_BIT_SET

存储过程IS_BIT_SET用于检查参数n是否存在于r。DBE_UTILITY. IS_BIT_SET函数原型为：

     
          DBE_UTILITY.IS_BIT_SET (
    r IN RAW, 
    n IN INTEGER)
RETURN INTEGER;

表9 DBE_UTILITY.IS_BIT_SET接口说明
参数名称	描述
r	4字节加上实际的十六进制字符串。
n	用于在二进制中判断是否存在该数值。

DBE_UTILITY.IS_CLUSTER_DATABASE
存储过程IS_CLUSTER_DATABASE用于判断当前数据库是否在数据库集群模式下运行。DBE_UTILITY.IS_CLUSTER_DATABASE函数原型为：
1 2

DBE_UTILITY.IS_CLUSTER_DATABASE RETURN BOOLEAN;

DBE_UTILITY.NAME_RESOLVE

存储过程NAME_RESOLVE解析给定的对象名称，包括同义词翻译和必要的授权检查。DBE_UTILITY.NAME_RESOLVE函数原型为：

     
          DBE_UTILITY.NAME_RESOLVE (
    name          IN   VARCHAR2,
    context       IN   INTEGER,
    schema        OUT VARCHAR2,
    part1         OUT VARCHAR2,
    part2         OUT VARCHAR2,
    dblink        OUT VARCHAR2,
    part1_type    OUT INTEGER,
    object_number OUT OID
);

**表10** DBE_UTILITY.NAME_RESOLVE接口说明
参数名称	描述
name	待解析对象名，结构为[[a.]b.]c[@d]。
context	返回哈希值的起始值。
schema	对象所在的模式。
part1	名称的第一部分，该字段的类型由part1_type指定。
part2	如果该字段不为空，则为子程序名称。
dblink	数据库链接。
part1_type	part1的类型： 5：synonym 7：procedure(top level) 8：function(top level)
object_number	对象标识。object_number在ORA数据库中类型为Number，表示对象标识，而GaussDB中对象标识类型为OID，并且不支持Number到OID的隐式转换。

DBE_UTILITY.NAME_TOKENIZE

存储过程NAME_TOKENIZE用于解析a [. b [. c ]][@ dblink ]形式的名字，如果名字带有双引号则去掉，否则变为大写字母。DBE_UTILITY.NAME_TOKENIZE函数原型为：

     
          DBE_UTILITY.NAME_TOKENIZE ( 
name    IN  VARCHAR2,
a       OUT VARCHAR2,
b       OUT VARCHAR2,
c       OUT VARCHAR2,
dblink  OUT VARCHAR2, 
nextpos OUT INTEGER
);

**表11** DBE_UTILITY.NAME_TOKENIZE接口说明
参数名称	描述
name	名字，由SQL标识符组成（比如, scott.foo@dblink）。
a	名字的第一个token。
b	名字的第二个token。
c	名字的第三个token。
dblink	数据库链接。
nextpos	字符串经过解析后的下一个位置。

DBE_UTILITY.OLD_CURRENT_SCHEMA
存储过程OLD_CURRENT_SCHEMA返回当前用户环境下的数据库模式名称。DBE_UTILITY.OLD_CURRENT_SCHEMA函数原型为：
1 2

DBE_UTILITY.OLD_CURRENT_SCHEMA() RETURN VARCHAR;

DBE_UTILITY.OLD_CURRENT_USER
存储过程OLD_CURRENT_USER返回当前用户的名称。DBE_UTILITY.OLD_CURRENT_USER函数原型为：
1 2

DBE_UTILITY.OLD_CURRENT_USER() RETURN VARCHAR2;

DBE_UTILITY.TABLE_TO_COMMA

存储过程TABLE_TO_COMMA将PL/SQL中的表名转换为用逗号隔开的名字列表的字符串。DBE_UTILITY.TABLE_TO_COMMA函数原型为：

     
          DBE_UTILITY.TABLE_TO_COMMA ( 
    tab    IN  UNCL_ARRAY, 
    tablen OUT BINARY_INTEGER,
    list   OUT VARCHAR2
);

**表12** DBE_UTILITY.TABLE_TO_COMMA接口说明
参数名称	描述
tab	包含表名的结构表数组。
tablen	结构表中的表个数。
list	以逗号分割表名的字符串。

DBE_UTILITY.GET_SQL_HASH_FUNC

函数GET_SQL_HASH_FUNC通过MD5算法输出一个给定字符串的hash值。DBE_UTILITY.GET_SQL_HASH_FUNC函数原型为：

      
           DBE_UTILITY.GET_SQL_HASH_FUNC(
    name       IN  VARCHAR2,
    hash       OUT RAW,
    last4bytes OUT BIGINT
);

**表13** DBE_UTILITY.GET_SQL_HASH_FUNC接口说明
参数名称	描述
name	待哈希转换的字符串。
hash	完整的16进制MD5哈希值。
last4bytes	MD5哈希值的最后四字节，以无符号整数形式展现。

设置set behavior_compat_options = 'proc_outparam_override' 参数后，请调用DBE_UTILITY.GET_SQL_HASH_FUNC函数，如调用DBE_UTILITY.GET_SQL_HASH则会报参数不匹配异常。

示例

    
     
       
       
         CREATE OR REPLACE PROCEDURE test_get_time1() 
AS
declare
    start_time  bigint;
    end_time  bigint;
BEGIN
    start_time:= dbe_utility.get_time ();
    pg_sleep(1);
    end_time:=dbe_utility.get_time ();
    dbe_output.print_line(end_time - start_time); 
END;
/
-- 给表名字符串做规范
declare
    cname varchar2(50);
begin
    dbe_utility.canonicalize('seg1', cname, 50);
    dbe_output.put_line(cname);
end;
/
-- 将输入的字符串转换成一个表名的数组  
DECLARE
 tab_list VARCHAR2(100) := 't1,t2';
 len BINARY_INTEGER;
 tab DBMS_UTILITY.LNAME_ARRAY;
BEGIN
 dbe_output.put_line('table list is ：' || tab_list);
 dbe_utility.comma_to_table(tab_list, len, tab);
END;
/
-- 查看数据库的版本号和兼容性版本号
declare
    v_version varchar2;
begin
    dbe_utility.db_version(v_version);
    v_version:=left(v_version, 8);
    dbe_output.print_line('version:' || v_version); 
end;
/
-- 查看当前CPU处理时间的测量值
DECLARE
    cputime NUMBER;
BEGIN
    cputime := dbe_utility.get_cpu_time;
    dbe_output.put_line('cpu time：' || cputime);
END;
/
-- 获取数据库所在平台字节序的大小端信息
BEGIN
    dbe_output.PUT_LINE(dbe_utility.GET_ENDIANNESS);
END;
/
-- 获取一个给定字符串的hash值
DECLARE
    result NUMBER(28);
BEGIN
    result := dbe_utility.get_hash_value('hello',10,10);
    dbe_output.put_line(result);
END;
/
-- 判断当前数据库是否为集群模式
DECLARE
    is_cluster BOOLEAN;
BEGIN
    is_cluster := dbe_utility.IS_CLUSTER_DATABASE;
    dbe_output.put_line('CLUSTER DATABASE: ' || CASE WHEN is_cluster THEN 'TRUE' ELSE 'FALSE' END);
END;
/
-- 获取当前用户环境下的数据库模式名称
DECLARE
    schm varchar2(100);
BEGIN
    schm := dbe_utility.old_current_schema;
    dbe_output.put_line('current schema: ' || schm);
END;
/
-- 获取当前用户名称
select dbe_utility.old_current_user from sys_dummy;

        

      

    
   