# DBE_UTILITY #### 接口介绍 高级功能包DBE_UTILITY支持的所有接口请参见[表1]。 表1DBE_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函数原型为： ``` DBE_UTILITY.FORMAT_ERROR_BACKTRACE() RETURN TEXT; ``` - DBE_UTILITY.FORMAT_ERROR_STACK 存储过程FORMAT_ERROR_STACK返回在执行过程中出现错误时，出现错误位置的具体信息。DBE_UTILITY.FORMAT_ERROR_STACK函数原型为： ``` DBE_UTILITY.FORMAT_ERROR_STACK() RETURN TEXT; ``` - DBE_UTILITY.FORMAT_CALL_STACK 存储过程FORMAT_CALL_STACK设置输出函数调用堆栈。DBE_UTILITY.FORMAT_CALL_STACK函数原型为： ``` DBE_UTILITY.FORMAT_CALL_STACK() RETURN TEXT; ``` - DBE_UTILITY.GET_TIME 存储过程GET_TIME设置输出时间，通常用于做差，单独的返回值没有意义。DBE_UTILITY.GET_TIME函数原型为： ``` 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 DEFAULT 1024 ); ``` 表2DBE_UTILITY.CANONICALIZE接口说明 | 参数名称 | 类型 | 入参/出参 | 是否可以为空 | 描述 | |:---|:---|:---|:---|:---| | name | VARCHAR2 | IN | 否 | 待规范的字符串。 | | canon_name | VARCHAR2 | OUT | 是 | 规范好的字符串。 | | canon_len | BINARY_INTEGER | IN | 是 | 要规范的字符串长度（以字节为单位）。若此参数的值小于待规范的字符串的实际长度（字节），则会以字节为粒度截断字符串。 | - 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 VARCHAR2[] ); ``` 表3DBE_UTILITY.COMMA_TO_TABLE接口说明 | 参数名称 | 类型 | 入参/出参 | 是否可以为空 | 描述 | |:---|:---|:---|:---|:---| | list | VARCHAR2 | IN | 否 | 逗号隔开的名字列表字符串。 | | tablen | BINARY_INTEGER | OUT | 是 | 列表名字的个数。 | | tab | VARCHAR2 | OUT | 是 | 转换后的表名称列表。 | - DBE_UTILITY.DB_VERSION 存储过程DB_VERSION返回数据库的版本号和兼容性版本号。DBE_UTILITY.DB_VERSION函数原型为： ``` DBE_UTILITY.DB_VERSION ( version OUT VARCHAR2 ); ``` 表4DBE_UTILITY.DB_VERSION接口说明 | 参数名称 | 类型 | 入参/出参 | 是否可以为空 | 描述 | |:---|:---|:---|:---|:---| | version | VARCHAR2 | OUT | 否 | 输出参数，表示内部的数据库软件版本信息，是一个字符串。 | - DBE_UTILITY.EXEC_DDL_STATEMENT 存储过程EXEC_DDL_STATEMENT用于执行用户输入的DDL语句。DBE_UTILITY.EXEC_DDL_STATEMENT函数原型为： ``` DBE_UTILITY.EXEC_DDL_STATEMENT ( parse_string IN TEXT ); ``` 表5DBE_UTILITY.EXEC_DDL_STATEMENT接口说明 | 参数名称 | 类型 | 入参/出参 | 是否可以为空 | 描述 | |:---|:---|:---|:---|:---| | parse_string | TEXT | IN | 是 | 需要执行的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 CLOB ); ``` 表6DBE_UTILITY.EXPAND_SQL_TEXT_PROC接口说明 | 参数名称 | 类型 | 入参/出参 | 是否可以为空 | 描述 | |:---|:---|:---|:---|:---| | input_sql_text | CLOB | IN | 否 | 输入的SQL文本。 | | output_sql_text | CLOB | OUT | 否 | 输出展开视图的SQL文本。 | ![](https://support.huaweicloud.com/distributed-devg-v3-gaussdb/public_sys-resources/note_3.0-zh-cn.png) 用户输入的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函数原型为： ``` DBE_UTILITY.GET_CPU_TIME() RETURN NUMBER; ``` - DBE_UTILITY.GET_ENDIANNESS 存储过程GET_ENDIANNESS用于获取数据库所在平台字节序的大小端信息。DBE_UTILITY. GET_ENDIANNESS函数原型为： ``` 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; ``` 表7DBE_UTILITY.GET_HASH_VALUE接口说明 | 参数名称 | 类型 | 入参/出参 | 是否可以为空 | 描述 | |:---|:---|:---|:---|:---| | name | VARCHAR2 | IN | 否 | 待哈希转换的字符串。 | | base | INTEGER | IN | 否 | 返回哈希值的起始值。 | | hash_size | INTEGER | IN | 否 | 哈希映射到的哈希表的大小。 | - 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 ); ``` 表8DBE_UTILITY.GET_SQL_HASH接口说明 | 参数名称 | 类型 | 入参/出参 | 是否可以为空 | 描述 | |:---|:---|:---|:---|:---| | name | VARCHAR2 | IN | 否 | 待哈希转换的字符串。 | | hash | RAW | OUT | 否 | 完整的16进制MD5哈希值。 | | last4bytes | BIGINT | OUT | 否 | MD5哈希值的最后四字节，以无符号整数形式展现。 | ![](https://support.huaweicloud.com/distributed-devg-v3-gaussdb/public_sys-resources/note_3.0-zh-cn.png) 设置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; ``` 表9DBE_UTILITY.IS_BIT_SET接口说明 | 参数名称 | 类型 | 入参/出参 | 是否可以为空 | 描述 | |:---|:---|:---|:---|:---| | r | RAW | IN | 否 | 4字节加上实际的十六进制字符串。 | | n | INTEGER | IN | 否 | 用于在二进制中判断是否存在该数值。 | - DBE_UTILITY.IS_CLUSTER_DATABASE 存储过程IS_CLUSTER_DATABASE用于判断当前数据库是否在数据库集群模式下运行。DBE_UTILITY.IS_CLUSTER_DATABASE函数原型为： ``` 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 ); ``` 表10DBE_UTILITY.NAME_RESOLVE接口说明 | 参数名称 | 类型 | 入参/出参 | 是否可以为空 | 描述 | |:---|:---|:---|:---|:---| | name | VARCHAR2 | IN | 否 | 待解析对象名，结构为\[\[a.\]b.\]c\[@d\]。 | | context | INTEGER | IN | 否 | 返回哈希值的起始值。 | | schema | VARCHAR2 | OUT | 否 | 对象所在的模式。 | | part1 | VARCHAR2 | OUT | 否 | 名称的第一部分，该字段的类型由part1_type指定。 | | part2 | VARCHAR2 | OUT | 是 | 如果该字段不为空，则为子程序名称。 | | dblink | VARCHAR2 | OUT | 是 | 数据库链接。 | | part1_type | INTEGER | OUT | 否 | part1的类型： - 5：synonym - 7：procedure(top level) - 8：function(top level) | | object_number | OID | OUT | 否 | 对象标识。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 ); ``` 表11DBE_UTILITY.NAME_TOKENIZE接口说明 | 参数名称 | 类型 | 入参/出参 | 是否可以为空 | 描述 | |:---|:---|:---|:---|:---| | name | VARCHAR2 | IN | 否 | 名字，由SQL标识符组成（比如, scott.foo@dblink）。 | | a | VARCHAR2 | OUT | 否 | 名字的第一个token。 | | b | VARCHAR2 | OUT | 是 | 名字的第二个token。 | | c | VARCHAR2 | OUT | 是 | 名字的第三个token。 | | dblink | VARCHAR2 | OUT | 是 | 数据库链接。 | | nextpos | INTEGER | OUT | 否 | 字符串经过解析后的下一个位置。 | - DBE_UTILITY.OLD_CURRENT_SCHEMA 存储过程OLD_CURRENT_SCHEMA返回当前用户环境下的数据库模式名称。DBE_UTILITY.OLD_CURRENT_SCHEMA函数原型为： ``` DBE_UTILITY.OLD_CURRENT_SCHEMA() RETURN VARCHAR; ``` - DBE_UTILITY.OLD_CURRENT_USER 存储过程OLD_CURRENT_USER返回当前用户的名称。DBE_UTILITY.OLD_CURRENT_USER函数原型为： ``` DBE_UTILITY.OLD_CURRENT_USER() RETURN TEXT; ``` - DBE_UTILITY.TABLE_TO_COMMA 存储过程TABLE_TO_COMMA将PL/SQL中的表名转换为用逗号隔开的名字列表的字符串。DBE_UTILITY.TABLE_TO_COMMA函数原型为： ``` DBE_UTILITY.TABLE_TO_COMMA ( tab IN VARCHAR2[], tablen OUT BINARY_INTEGER, list OUT VARCHAR2 ); ``` 表12DBE_UTILITY.TABLE_TO_COMMA接口说明 | 参数名称 | 类型 | 入参/出参 | 是否可以为空 | 描述 | |:---|:---|:---|:---|:---| | tab | VARCHAR2\[\] | IN | 否 | 包含表名的结构表数组。 | | tablen | BINARY_INTEGER | OUT | 否 | 结构表中的表个数。 | | list | VARCHAR2 | OUT | 否 | 以逗号分隔表名的字符串。 | - 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 ); ``` 表13DBE_UTILITY.GET_SQL_HASH_FUNC接口说明 | 参数名称 | 类型 | 入参/出参 | 是否可以为空 | 描述 | |:---|:---|:---|:---|:---| | name | VARCHAR2 | IN | 否 | 待哈希转换的字符串。 | | hash | RAW | OUT | 否 | 完整的16进制MD5哈希值。 | | last4bytes | BIGINT | OUT | 否 | MD5哈希值的最后四字节，以无符号整数形式展现。 | ![](https://support.huaweicloud.com/distributed-devg-v3-gaussdb/public_sys-resources/note_3.0-zh-cn.png) 设置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; / CREATE PROCEDURE -- 给表名字符串做规范 declare cname varchar2(50); begin dbe_utility.canonicalize('seg1', cname, 50); dbe_output.put_line(cname); end; / -- 预期结果为： SEG1 ANONYMOUS BLOCK EXECUTE -- 将输入的字符串转换成一个表名的数组 DECLARE tab_list VARCHAR2(100) := 't1,t2'; len BINARY_INTEGER; tab varchar2[]; BEGIN dbe_output.put_line('table list is ：' || tab_list); dbe_utility.comma_to_table(tab_list, len, tab); END; / -- 预期结果为： table list is: t1,t2 ANONYMOUS BLOCK EXECUTE -- 查看数据库的版本号和兼容性版本号 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; / -- 预期结果为： version:gaussdb ANONYMOUS BLOCK EXECUTE -- 查看当前CPU处理时间的测量值 DECLARE cputime NUMBER; BEGIN cputime := dbe_utility.get_cpu_time; dbe_output.put_line('cpu time：' || cputime); END; / -- 预期结果为（数值并非固定）： cpu time：70179 ANONYMOUS BLOCK EXECUTE -- 获取数据库所在平台字节序的大小端信息 BEGIN dbe_output.PUT_LINE(dbe_utility.GET_ENDIANNESS); END; / -- 预期结果为： 2 ANONYMOUS BLOCK EXECUTE -- 获取一个给定字符串的hash值 DECLARE result NUMBER(28); BEGIN result := dbe_utility.get_hash_value('hello',10,10); dbe_output.put_line(result); END; / -- 预期结果为： 11 ANONYMOUS BLOCK EXECUTE -- 判断当前数据库是否为集群模式 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; / -- 预期结果为： CLUSTER DATABASE: TRUE ANONYMOUS BLOCK EXECUTE -- 获取当前用户环境下的数据库模式名称 DECLARE schm varchar2(100); BEGIN schm := dbe_utility.old_current_schema; dbe_output.put_line('current schema: ' || schm); END; / -- 预期结果为（结果为当前数据库的模式名，并非固定）： current schema: public ANONYMOUS BLOCK EXECUTE -- 获取当前用户名称 select dbe_utility.old_current_user from sys_dummy; -- 预期结果为（结果为当前数据库的用户名，并非固定）： old_current_user ------------------ test (1 row) ```