接口介绍 高级功能包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_OBJE CTS 内部函数，不建议用户使用。 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;

PRVT_ILM PRVT_ILM接口为ILM特性内部使用，用户无法直接调用，只列举接口名称，不做详细接口原型描述。 接口名称 描述 be_active_ado_window 维护窗口触发动作，刷新ilmadowindow触发时间及动作。 be_create_ado_window_for_each_db 维护窗口触发动作，在实例的每个数据库中创建ilmadowindow。 be_execute_ilm ilmadowind执行动作，进行自动评估。 be_execute_ilm_dn 用于分布式DN上的自动评估。该操作会影响集群整体的ILM后台调度。 flush_task_executestate 自动调度任务刷新task状态。 generate_taskoid CN生成用于本次调度的taskid。 evaluate_obj_policy 触发调度后对数据对象进行评估。 change_be_ilm dbe_ilm_admin.enable_ilm()和disable_ilm()帮助函数。该操作会影响集群整体的ILM后台调度。 get_compression_ratio dbe_compression.get_compression_ratio()帮助函数。 get_compression_type dbe_compression.get_compression_type()帮助函数。 get_lastmodified_time dbe_heat_map.row_heat_map()帮助函数。 ilm_job_action 压缩任务执行体，分布式DN使用。 delete_expired_ilm_log 清理过期日志，分布式使用。 delete_gs_ilm_task 操作特性相关系统表，分布式DN使用。 insert_gs_ilm_jobdetail 操作特性相关系统表，分布式DN使用。 insert_gs_ilm_task 操作特性相关系统表，分布式DN使用。 insert_gs_ilm_taskdetail 操作特性相关系统表，分布式DN使用。 update_gs_ilm_jobdetail 操作特性相关系统表，分布式DN使用。 update_gs_ilm_object 操作特性相关系统表，分布式DN使用。 update_gs_ilm_param 操作特性相关系统表，分布式DN使用。该操作会影响集群整体的ILM后台调度。 update_gs_ilm_task 操作特性相关系统表，分布式DN使用。 gs_ilm_ticker 维护窗口执行动作，执行一次打点，记录lsn与时间的映射关系。 compress_blocks prvt_ilm.ilm_job_action()帮助函数。 compress_block_single 废弃接口，请勿再使用。 get_job_status dbe_ilm.stop_ilm帮助函数。 insert_gs_ilm_param 操作特性相关系统表。 query_unfinishedjob_num 查询是否存在还没有结束的job，包括初始和运行中的状态。 update_gs_ilm_object_flag2 操作特性相关系统表，分布式DN使用。 ilm_seq_nextval 用于获取ilm的下一个sequence值。 ilm_seq_setval 用于设置ilm的当前sequence值。 check_compatibility 用于统一判断数据库兼容性模式的帮助函数。 set_pg_settings 用于设置数据库兼容性模式特性GUC参数的帮助函数。 check_seq 保证gsilmtask_seq当前值大于gs_ilm_task表最大taskoid，分布式CN使用。 父主题： 二次封装接口（推荐）

数据类型介绍 高级包DBE_DESCRIBE内置了两个数据类型，这两个数据类型使用自定义类型创建，用于DESCRIBE_PROCEDURE接口的返回值。 DBE_DESCRIBE.NUMBER_TABLE 该类型是NUMBER的TABLE类型，通过TABLE OF语法实现。 DBE_DESCRIBE.NUMBER_TABLE类型的原型为： 1 CREATE TYPE DBE_DESCRIBE.NUMBER_TABLE AS TABLE OF NUMBER INDEX BY INTEGER; DBE_DESCRIBE.VARCHAR2_TABLE 该类型是VARCHAR2的TABLE类型，通过TABLE OF语法实现。 DBE_DESCRIBE.VARCHAR2_TABLE类型的原型为： 1 CREATE TYPE DBE_DESCRIBE.VARCHAR2_TABLE AS TABLE OF VARCHAR2(30) INDEX BY INTEGER;

约束说明 job只能通过dbe_task高级包提供的接口进行创建、更新、删除操作，因为高级包的接口中会考虑所有数据库主节点间job信息的同步和pg_job与pg_job_proc表主键的关联操作，如果通过DML语句对pg_job表进行增删改，会导致job信息在数据库主节点间不一致和系统表无法关联变更的混乱问题，会严重影响job内部的管理。 由于用户创建的每个任务和数据库主节点绑定，当任务运行过程中，该数据库主节点故障，则该任务的状态无法实时刷新，仍为‘r’状态，需要等数据库主节点启动正常后才能刷新为‘s’状态。如果在任务未执行时数据库主节点故障，则该数据库主节点上的任务都得不到正常的调度和执行，需要人为干预让该数据库主节点恢复正常，或进行节点删除/替换，job才能正常的调度和执行。 job在定时执行过程中，需要在当前job所属的数据库主节点上实时更新该job的运行状态、最近执行开始时间、最近执行结束时间、下次开始时间和失败次数（如果job执行失败）等相关参数信息到pg_job系统表中，并同步到其他数据库主节点，保证job信息的一致性。如果其他数据库主节点存在节点故障，那么job所属数据库主节点会同步超时重发的操作，导致job执行时间变长，但数据库主节点间同步超时失败后，原数据库主节点上pg_job表中job的相关信息仍然能正常更新，且job能正常执行成功。当故障数据库主节点恢复正常后，可能出现该数据库主节点上pg_job表中当前job的执行时间、运行状态等参数与原数据库主节点上不一致的情况，需要原数据库主节点上再次执行该job后才能保证job信息的同步。 对于并发同时有多个job到达执行时间的场景，由于会为每个job创建一个线程来执行job，并且系统内部启动每个线程的时间会有延迟，因此会导致同时并发执行的job的开始时间有延迟，每个job的延迟时间在0.1ms左右。

接口介绍 高级功能包DBE_XMLDOM用于访问XMLType对象，实现DOM(Document Object Model)，用于访问HTML和XML DOCUMENTS API。高级功能包DBE_XMLDOM支持的所有类型请参见表1，DBE_XMLDOM支持的所有接口请参见表2。 DBE_XMLDOM高级包在字符集设置为SQL_ASCII的数据库内使用的情况下，输入超出ASCII范围的字符，会导致报错。 表1 DBE_XMLDOM数据类型说明 类型名称 描述 DOMATTR 实现DOM Attribute接口。 DOMDOCUMENT 实现DOM Document接口。 DOMELEMENT 实现DOM Element接口。 DOMNAMEDNODEMAP 实现DOM Named Node Map接口。 DOMNODELIST 实现DOM Node List接口。 DOMNODE 实现DOM Node接口。 DOMTEXT 实现DOM Text接口。 表2 DBE_XMLDOM接口参数说明 接口名称 描述 DBE_XMLDOM.APPENDCHILD 将newchild node添加到parent(n)节点最后面，并返回新添加的Node节点。 DBE_XMLDOM.CREATEELEMENT 创建指定名称的DOMELEMENT对象。 DBE_XMLDOM.CREATETEXTNODE 创建DOMTEXT节点。 DBE_XMLDOM.FREEDOCUMENT 释放DOMDOCUMENT节点相关资源。 DBE_XMLDOM.FREEELEMENT 释放DOMELEMENT节点相关资源。 DBE_XMLDOM.FREENODE 释放DOMNODE节点相关资源。 DBE_XMLDOM.FREENODELIST 释放DOMNODELIST节点相关资源。 DBE_XMLDOM.GETATTRIBUTE 按名称返回DOMELEMENT属性的值。 DBE_XMLDOM.GETATTRIBUTES 将DOMNODE节点属性值作为map返回。 DBE_XMLDOM.GETCHILDNODES 将节点下的若干子节点转换成节点列表。 DBE_XMLDOM.GETCHILDRENBYTAGNAME 按名称返回DOMELEMENT的子节点。 DBE_XMLDOM.GETDOCUMENTELEMENT 返回指定DOCUMENT的首个子节点。 DBE_XMLDOM.GETFIRSTCHILD 返回第一个子节点。 DBE_XMLDOM.GETLASTCHILD 返回最后一个子节点。 DBE_XMLDOM.GETLENGTH 获取给定节点中的节点个数。 DBE_XMLDOM.GETLOCALNAME 检索节点的本地名称。 DBE_XMLDOM.GETNAMEDITEM 检索由名称指定的节点。 DBE_XMLDOM.GETNEXTSIBLING 返回该节点的下一个节点。 DBE_XMLDOM.GETNODENAME 返回节点名称。 DBE_XMLDOM.GETNODETYPE 返回节点类型。 DBE_XMLDOM.GETNODEVALUE 此函数用于获取节点的值，具体取决于其类型。 DBE_XMLDOM.GETPARENTNODE 检索此节点的父节点。 DBE_XMLDOM.GETTAGNAME 返回指定DOMELEMENT的标签名称。 DBE_XMLDOM.HASCHILDNODES 检查DOMNODE对象是否拥有任一子节点。 DBE_XMLDOM.IMPORTNODE 复制节点并为该节点指定所属文档。 DBE_XMLDOM.ISNULL 检测节点是否为空。 DBE_XMLDOM.ITEM 返回映射中与索引参数对应的项。 DBE_XMLDOM.MAKEELEMENT 将DOMNODE对象转换为DOMELEMENT类型。 DBE_XMLDOM.MAKENODE 将节点强制转换为DOMNODE类型。 DBE_XMLDOM.NEWDOMDOCUMENT 返回新的DOMDOCUMENT对象。 DBE_XMLDOM.SETATTRIBUTE 按名称设置DOMELEMENT属性的值。 DBE_XMLDOM.SETCHARSET 设置DOMDOCUMENT的CHATSET字符集。 DBE_XMLDOM.SETDOCTYPE 设置DOMDOCUMENT的外部DTD。 DBE_XMLDOM.SETNODEVALUE 此函数用于向DOMNODE对象中设置节点的值。 DBE_XMLDOM.WRITETOBUFFER 将 XML 节点写入指定缓冲区。 DBE_XMLDOM.WRITETOCLOB 将 XML 节点写入指定CLOB。 DBE_XMLDOM.WRITETOFILE 将 XML 节点写入指定文件。 DBE_XMLDOM.GETSESSIONTREENUM 显示当前session中所有类型的dom树的数量。 DBE_XMLDOM.GETDOCTREESINFO 显示document类型的dom树的内存占用、节点数量等统计信息。 DBE_XMLDOM.GETDETAILDOCTREEINFO 显示特定的document变量的各类型节点数量。 DBE_XMLDOM.GETELEMENTSB.... 返回匹配TAGNAME的DOMNODELIST节点列表。

约束说明 使用summit/id_submit创建一个新job后，该job从属于当前coordinator（即：该job仅在当前coordinator上调度和执行），其他coordinator不会调度和执行该job，如果出现coordinator节点故障，无法保证job正常执行。建议使用PKG_SERVICE.SUBMIT_ON_N....接口，将job执行节点指定为CCN，以保证节点故障时job仍然可用。不是所有coordinator都可以查看、修改、删除其他CN创建的job。 job只能通过dbe_task高级包提供的接口进行创建、更新、删除操作，因为高级包的接口中会考虑所有CN间job信息的同步和pg_job与pg_job_proc表主键的关联操作，如果通过DML语句对pg_job表进行增删改，会导致job信息在CN间不一致和系统表无法关联变更的混乱问题，会严重影响job内部的管理。 由于用户创建的每个任务和CN绑定，当任务运行过程中，该CN故障，则该任务的状态无法实时刷新，仍为‘r’状态，需要等CN启动正常后才能刷新为‘s’状态。如果在任务未执行时CN故障，则该CN上的任务都得不到正常的调度和执行，需要人为干预让该CN恢复正常，或进行节点删除/替换，job才能正常的调度和执行。 job在定时执行过程中，需要在当前job所属的CN上实时更新该job的运行状态、最近执行开始时间、最近执行结束时间、下次开始时间、失败次数（如果job执行失败）等相关参数信息到pg_job系统表中，并同步到其他CN，保证job信息的一致性。如果其他CN存在节点故障，那么job所属CN会同步超时重发的操作，导致job执行时间变长，但CN间同步超时失败后，原CN上pg_job表中job的相关信息仍然能正常更新，且job能正常执行成功。当故障CN恢复正常后，可能出现该CN上pg_job表中当前job的执行时间、运行状态等参数与原CN上不一致的情况，需要原CN上再次执行该job后才能保证job信息的同步。 对于并发同时有多个job到达执行时间的场景，由于会为每个job创建一个线程来执行job，由于系统内部启动每个线程的时间会有延迟，因此会导致同时并发执行的job开始时间有延迟，每个job的延迟时间在0.1ms左右。

接口介绍 表1 DBE_STATS接口总览 接口名称 描述 DBE_STATS.LOCK_TABLE_STATS 锁定表级统计信息。 DBE_STATS.LOCK_PARTITION_STATS 锁定分区级统计信息。 DBE_STATS.LOCK_COLUMN_STATS 锁定列级统计信息。 DBE_STATS.LOCK_SCHEMA_STATS 锁定指定schema下所有表相关的统计信息。 DBE_STATS.UNLOCK_TABLE_STATS 解锁表级统计信息。 DBE_STATS.UNLOCK_PARTITION_STATS 解锁分区级统计信息。 DBE_STATS.UNLOCK_COLUMN_STATS 解锁列级统计信息。 DBE_STATS.UNLOCK_SCHEMA_STATS 解锁指定schema下所有表相关的统计信息。 DBE_STATS.RESTORE_TABLE_STATS 回退表级统计信息到指定时间点。 DBE_STATS.RESTORE_PARTITION_STATS 回退分区级统计信息到指定时间点。 DBE_STATS.RESTORE_COLUMN_STATS 回退列级统计信息到指定时间点。 DBE_STATS.RESTORE_SCHEMA_STATS 回退指定schema下所有表相关的统计信息到指定时间点。 DBE_STATS.PURGE_STATS 清除指定时间节点前的所有历史统计信息。 DBE_STATS.GET_STATS_HISTORY_RETENTION 获取历史统计信息的保留时间。 DBE_STATS.GET_STATS_HISTORY_AVAILABILITY 获取最早可用的历史统计信息的时间。 DBE_STATS.CREATE_STAT_TABLE 创建用于保存统计信息的统计表。 DBE_STATS.DROP_STAT_TABLE 删除用于保存统计信息的统计表。 DBE_STATS.EXPORT_INDEX_STATS 检索指定索引的统计信息并存储在用户统计信息表中。 DBE_STATS.EXPORT_TABLE_STATS 检索指定表的统计信息并存储在用户统计信息表中。 DBE_STATS.EXPORT_COLUMN_STATS 检索指定列的统计信息并存储在用户统计信息表中。 DBE_STATS.EXPORT_SCHEMA_STATS 检索指定schema的统计信息并存储在用户统计信息表中。 DBE_STATS.IMPORT_INDEX_STATS 从用户统计信息表中检索指定索引的统计信息，并将其写回系统表。 DBE_STATS.IMPORT_TABLE_STATS 从用户统计信息表中检索指定表的统计信息，并将其写回系统表。 DBE_STATS.IMPORT_COLUMN_STATS 从用户统计信息表中检索指定列的统计信息，并将其写回系统表。 DBE_STATS.IMPORT_SCHEMA_STATS 从用户统计信息表中检索指定schema的统计信息，并将其写回系统表。 DBE_STATS.SET_COLUMN_STATS 设置列相关的统计信息，包括单列、多列、表达式统计信息。 DBE_STATS.SET_INDEX_STATS 设置索引相关的统计信息。 DBE_STATS.SET_TABLE_STATS 设置表相关的统计信息。 DBE_STATS.DELETE_COLUMN_STATS 删除列相关的统计信息，包括单列、多列、表达式统计信息。 DBE_STATS.DELETE_INDEX_STATS 删除索引相关的统计信息。 DBE_STATS.DELETE_TABLE_STATS 删除表相关的统计信息。 DBE_STATS.DELETE_SCHEMA_STATS 删除schema下所有表、索引、列相关的统计信息。

数据类型介绍 高级包DBE_DESCRIBE内置了两个数据类型，这两个数据类型使用自定义类型创建，用于DESCRIBE_PROCEDURE接口的返回值。 DBE_DESCRIBE.NUMBER_TABLE 该类型是NUMBER的TABLE类型，通过TABLE OF语法实现。 DBE_DESCRIBE.NUMBER_TABLE类型的原型为： 1 CREATE TYPE DBE_DESCRIBE.NUMBER_TABLE AS TABLE OF NUMBER INDEX BY INTEGER; DBE_DESCRIBE.VARCHAR2_TABLE 该类型是VARCHAR2的TABLE类型，通过TABLE OF语法实现。 DBE_DESCRIBE.VARCHAR2_TABLE类型的原型为： 1 CREATE TYPE DBE_DESCRIBE.VARCHAR2_TABLE AS TABLE OF VARCHAR2(30) INDEX BY INTEGER;

示例 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 BEGIN DBE_OUTPUT.SET_BUFFER_SIZE(50); DBE_OUTPUT.PRINT('hello, '); DBE_OUTPUT.PRINT_LINE('database!');--输出hello, database! END; / -- 预期结果为： hello, database! ANONYMOUS BLOCK EXECUTE -- 测试disable禁用put、put_line、new_line、get_line、get_lines调用,测试put_line不输出 BEGIN dbe_output.disable(); dbe_output.put_line('1'); END; / -- 预期结果为： ANONYMOUS BLOCK EXECUTE -- 测试enable启用put、put_line、new_line、get_line、get_lines调用，测试put_line输出1 BEGIN dbe_output.enable(); dbe_output.put_line('1'); END; / -- 预期结果为： 1 ANONYMOUS BLOCK EXECUTE -- 测试put，输入字符串a放入到缓冲区，末尾不加换行符，a不输出 BEGIN dbe_output.enable(); dbe_output.put('a'); END; / -- 预期结果为： ANONYMOUS BLOCK EXECUTE -- 测试new_line,添加换行，输出a BEGIN dbe_output.enable(); dbe_output.put('a'); dbe_output.new_line; END; / -- 预期结果为： a ANONYMOUS BLOCK EXECUTE -- 测试get_line获取缓冲区数据保存到变量，使用put_line输出 DECLARE line VARCHAR(32672); status INTEGER := 0; BEGIN dbe_output.put_line('hello'); dbe_output.get_line(line, status); dbe_output.put_line('-----------'); dbe_output.put_line(line); dbe_output.put_line(status); END; / -- 预期结果为： ----------- hello 0 ANONYMOUS BLOCK EXECUTE -- 测试get_lines获取缓冲区多行内容，使用put_line输出 DECLARE lines varchar[]; linenum integer; BEGIN dbe_output.put_line('line 1'); dbe_output.put_line('line 2'); dbe_output.put_line('line 3'); linenum := 100; dbe_output.get_lines(lines, linenum); dbe_output.put_line('num: ' || linenum); FOR i IN 1 .. linenum LOOP dbe_output.put_line(lines[i]); END LOOP; END; / -- 预期结果为： num: 3 line 1 line 2 line 3 ANONYMOUS BLOCK EXECUTE 当服务端的字符编码类型server_encoding不为UTF-8时，如果数据中存在字符编码属于合法的UTF-8编码，DBE_OUTPUT.PUTLINE函数和DBE_OUTPUT.PUT函数在处理该字符编码时会将其按照UTF8编码逻辑进行处理，将其先转换成server_encoding的编码格式后再进行后续操作，这样可能会导致函数返回值不符合预期或发生报错；当开启GUC参数enable_convert_illegal_char后，DBE_OUTPUT.PUTLINE函数和DBE_OUTPUT.PUT函数在处理此类编码的表现与参数关闭时保持一致，特殊字符不会以占位符形式输出。因此，不建议用户对含有特殊字符的数据使用DBE_OUTPUT.PUTLINE函数和DBE_OUTPUT.PUT函数。

接口介绍 高级功能包DBE_OUTPUT支持的所有接口请参见表 DBE_OUTPUT。 表1 DBE_OUTPUT 接口名称 描述 DBE_OUTPUT.PRINT_LINE 输出指定的文本，并添加换行符。 DBE_OUTPUT.PRINT 输出指定的文本，不添加换行符。 DBE_OUTPUT.SET_BUFFER_SIZE 设置输出缓冲区的大小，如果不指定则缓冲区最大能容纳20000字节，如果指定小于等于2000字节，则缓冲区允许容纳2000字节。 DBE_OUTPUT.DISABLE 禁用PUT、PUT_LINE、NEW_LINE、GET_LINE和GET_LINES调用，并清空输出缓冲区。 DBE_OUTPUT.ENABLE 开启缓冲区，允许对PUT、PUT_LINE、NEW_LINE、GET_LINE和GET_LINES的调用，设置缓冲区大小。 DBE_OUTPUT.GET_LINE 从缓冲区中以换行符作为分界获取一行数据，获取的数据将不会输出到客户端。 DBE_OUTPUT.GET_LINES 以VARCHAR数组的形式获取缓冲区的指定行数的字符串，被取出的内容将会在缓冲区中清除，不会输出到客户端。 DBE_OUTPUT.NEW_LINE 放置一行在缓冲区末尾，放置行尾标记，空出新的一行。 DBE_OUTPUT.PUT 将输入字符串放入到缓冲区，末尾不加换行符，在匿名块执行结束时会将以换行符结尾的行输出显示。 DBE_OUTPUT.PUT_LINE 将输入字符串放入到缓冲区，并末尾添加换行符，在匿名块执行结束时会将以换行符结尾的行输出显示。 DBE_OUTPUT.PRINT_LINE 存储过程PRINT_LINE输出指定的文本，并添加换行符。DBE_OUTPUT.PRINT_LINE函数原型为： 1 2 DBE_OUTPUT.PRINT_LINE ( format IN VARCHAR2); 表2 DBE_OUTPUT.PRINT_LINE接口参数说明 参数 描述 format 输出的文本。 DBE_OUTPUT.PRINT 存储过程PRINT输出指定的文本，不添加换行符。DBE_OUTPUT.PRINT函数原型为： 1 2 DBE_OUTPUT.PRINT ( format IN VARCHAR2); 表3 DBE_OUTPUT.PRINT接口参数说明 参数 描述 format 输出的文本。 DBE_OUTPUT.SET_BUFFER_SIZE 存储过程SET_BUFFER_SIZE设置输出缓冲区的大小，如果不指定的话缓冲区最大只能容纳20000字节。DBE_OUTPUT.SET_BUFFER_SIZE函数原型为： 1 2 DBE_OUTPUT.SET_BUFFER_SIZE ( size IN INTEGER default 20000); 表4 DBE_OUTPUT.SET_BUFFER_SIZE接口参数说明 参数 描述 size 设置输出缓冲区的大小。

示例 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 --step1 创建表和存储过程 gaussdb=# DROP TABLE IF EXISTS t1; gaussdb=# CREATE TABLE t1 (i int); gaussdb=# CREATE OR REPLACE PROCEDURE p1() AS sql_stmt varchar2(200); result number; BEGIN for i in 1..1000 loop insert into t1 values(1); end loop; sql_stmt := 'select count(*) from t1'; EXECUTE IMMEDIATE sql_stmt into result; END; / gaussdb=# CREATE OR REPLACE PROCEDURE p2() AS BEGIN p1(); END; / gaussdb=# CREATE OR REPLACE PROCEDURE p3() AS BEGIN p2(); END; / --step2 调用plprofiler接口对存储过程进行profiling gaussdb=# SELECT dbe_profiler.pl_start_profiling('123'); gaussdb=# CALL p3(); --step3 查询相关profiling信息 --查询dbe_profiler.pl_profiling_functions表查看此次profiling涉及的存储过程 gaussdb=# SELECT * FROM dbe_profiler.pl_profiling_functions ORDER BY run_id, funcoid; run_id | funcoid | schema | funcname | total_occur | total_time ---------------------+---------+--------+----------+-------------+------------ 140300887521024_123 | 16770 | public | p1() | 1 | 54217 140300887521024_123 | 16771 | public | p2() | 1 | 54941 140300887521024_123 | 16772 | public | p3() | 1 | 55758 (3 rows) --查询dbe_profiler.pl_profiling_details表查看存过内每条语句的执行时间细节 gaussdb=# SELECT * FROM dbe_profiler.pl_profiling_details WHERE funcoid = 16770 ORDER BY run_id, funcoid, line#; run_id | funcoid | line# | source | cmd_type | total_occur | total_time | max_time | min_time ---------------------+---------+-------+---------------------------------------------+------------+-------------+------------+----------+---------- 140300887521024_123 | 16770 | 1 | DECLARE | | 0 | 0 | 0 | 0 140300887521024_123 | 16770 | 2 | sql_stmt varchar2(200); | | 0 | 0 | 0 | 0 140300887521024_123 | 16770 | 3 | result number; | | 0 | 0 | 0 | 0 140300887521024_123 | 16770 | 4 | begin | | 0 | 0 | 0 | 0 140300887521024_123 | 16770 | 5 | for i in 1..1000 loop | FORI | 1 | 52496 | 52496 | 52496 140300887521024_123 | 16770 | 6 | insert into t1 values(1); | EXE CS QL | 1000 | 51970 | 2115 | 47 140300887521024_123 | 16770 | 7 | end loop; | | 0 | 0 | 0 | 0 140300887521024_123 | 16770 | 8 | sql_stmt := 'select count(*) from t1'; | ASSIGN | 1 | 446 | 446 | 446 140300887521024_123 | 16770 | 9 | EXECUTE IMMEDIATE sql_stmt into result; | DYNEXECUTE | 1 | 1271 | 1271 | 1271 140300887521024_123 | 16770 | 10 | end | | 0 | 0 | 0 | 0 (10 rows) --查询dbe_profiler.pl_profiling_callgraph表查看调用栈信息和对应每个存过执行的整体时间（total_time、self_time对应调用栈栈顶存储过程的总时间和自身执行时间） gaussdb=# SELECT * FROM dbe_profiler.pl_profiling_callgraph ORDER BY run_id, stack; run_id | stack | self_time ---------------------+---------------------------------------------------------------------------+----------- 140300887521024_123 | {"public.p3() oid=16772"} | 817 140300887521024_123 | {"public.p3() oid=16772","public.p2() oid=16771"} | 724 140300887521024_123 | {"public.p3() oid=16772","public.p2() oid=16771","public.p1() oid=16770"} | 54217 (3 rows) --查询dbe_profiler.pl_profiling_trackinfo表查看存储过程每个阶段的执行时间 gaussdb=# SELECT step_name, loops_count FROM dbe_profiler.pl_profiling_trackinfo WHERE funcoid=16770; step_name | loops_count --------------+------------- init | 1 package | 1 spictx | 1 compile | 1 exec_context | 1 execute | 1 exec_cursor | 1 cleanup | 1 finsh | 1 (9 rows) --step4 删除系统表数据 gaussdb=# SELECT dbe_profiler.pl_clear_profiling(''); gaussdb=# SELECT step_name, loops_count FROM dbe_profiler.pl_profiling_trackinfo WHERE funcoid=16770; step_name | loops_count -----------+------------- (0 rows) gaussdb=# DROP TABLE t1; --step5 profiling包含自治事务的存储过程。 --建表 gaussdb=# CREATE TABLE t2(a int, b int); --创建包含自治事务的存储过程 gaussdb=# CREATE OR REPLACE PROCEDURE autonomous(a int, b int) AS DECLARE num3 int := a; num4 int := b; PRAGMA AUTONOMOUS_TRANSACTION; BEGIN insert into t2 values(num3, num4); dbe_output.print_line('just use call.'); END; / --创建调用自治事务存储过程的普通存储过程 gaussdb=# CREATE OR REPLACE PROCEDURE autonomous_1(a int, b int) AS DECLARE BEGIN dbe_output.print_line('just no use call.'); insert into t2 values(666, 666); autonomous(a,b); END; / gaussdb=# SELECT dbe_profiler.pl_start_profiling ('100'); gaussdb=# CALL autonomous(11,22); --查询表信息 gaussdb=# SELECT * FROM dbe_profiler.pl_profiling_functions ORDER BY run_id, funcoid; run_id | funcoid | schema | funcname | total_occur | total_time --------+---------+--------+----------+-------------+------------ (0 rows) gaussdb=# SELECT * FROM dbe_profiler.pl_profiling_details ORDER BY run_id, funcoid, line#; run_id | funcoid | line# | source | cmd_type | total_occur | total_time | max_time | min_time --------+---------+-------+--------+----------+-------------+------------+----------+---------- (0 rows) gaussdb=# SELECT * FROM dbe_profiler.pl_profiling_callgraph ORDER BY run_id, stack; run_id | stack | self_time --------+-------+----------- (0 rows) gaussdb=# SELECT * FROM dbe_profiler.pl_profiling_trackinfo ORDER BY run_id, funcoid; run_id | funcoid | step_name | loops_count | max_time | min_time | avg_time | total_time --------+---------+-----------+-------------+----------+----------+----------+------------ (0 rows) gaussdb=# SELECT dbe_profiler.pl_start_profiling ('101'); gaussdb=# CALL autonomous_1(11,22); gaussdb=# SELECT * FROM dbe_profiler.pl_profiling_functions ORDER BY run_id, funcoid; run_id | funcoid | schema | funcname | total_occur | total_time ---------------------+---------+------------+----------------+-------------+------------ 140421237831424_101 | 10422 | dbe_output | print_line() | 1 | 758 140421237831424_101 | 16771 | public | autonomous_1() | 1 | 23855 (2 rows) gaussdb=# SELECT * FROM dbe_profiler.pl_profiling_details ORDER BY run_id, funcoid, line#; run_id | funcoid | line# | source | cmd_type | total_occur | total_time | max_time | min_time ---------------------+---------+-------+---------------------------------------------+----------+-------------+------------+----------+---------- 140421237831424_101 | 10422 | 1 | | | 0 | 0 | 0 | 0 140421237831424_101 | 10422 | 2 | BEGIN | | 0 | 0 | 0 | 0 140421237831424_101 | 10422 | 3 | PKG_UTIL.io_print(format, true); | PERFORM | 1 | 754 | 754 | 754 140421237831424_101 | 10422 | 4 | END; | | 0 | 0 | 0 | 0 140421237831424_101 | 10422 | 5 | | | 0 | 0 | 0 | 0 140421237831424_101 | 16771 | 1 | | | 0 | 0 | 0 | 0 140421237831424_101 | 16771 | 2 | DECLARE | | 0 | 0 | 0 | 0 140421237831424_101 | 16771 | 3 | BEGIN | | 0 | 0 | 0 | 0 140421237831424_101 | 16771 | 4 | dbe_output.print_line('just no use call.'); | PERFORM | 1 | 2435 | 2435 | 2435 140421237831424_101 | 16771 | 5 | insert into t2 values(666, 666); | EXECSQL | 1 | 602 | 602 | 602 140421237831424_101 | 16771 | 6 | autonomous(a,b); | PERFORM | 1 | 20813 | 20813 | 20813 140421237831424_101 | 16771 | 7 | END | | 0 | 0 | 0 | 0 (12 rows) gaussdb=# SELECT * FROM dbe_profiler.pl_profiling_callgraph ORDER BY run_id, stack; run_id | stack | self_time ---------------------+-------------------------------------------------------------------------+----------- 140421237831424_101 | {"public.autonomous_1() oid=16771"} | 23097 140421237831424_101 | {"public.autonomous_1() oid=16771","dbe_output.print_line() oid=10422"} | 758 (2 rows) gaussdb=# SELECT * FROM dbe_profiler.pl_profiling_trackinfo ORDER BY run_id, funcoid; run_id | funcoid | step_name | loops_count | max_time | min_time | avg_time | total_time ---------------------+---------+--------------+-------------+----------+----------+----------+------------ 140421237831424_101 | 10422 | init | 1 | 0 | 0 | 0 | 0 140421237831424_101 | 10422 | package | 1 | 9 | 9 | 9 | 9 140421237831424_101 | 10422 | spictx | 1 | 1 | 1 | 1 | 1 140421237831424_101 | 10422 | compile | 1 | 383 | 383 | 383 | 383 140421237831424_101 | 10422 | exec_context | 1 | 1 | 1 | 1 | 1 140421237831424_101 | 10422 | execute | 1 | 1301 | 1301 | 1301 | 1301 140421237831424_101 | 10422 | exec_cursor | 1 | 3 | 3 | 3 | 3 140421237831424_101 | 10422 | cleanup | 1 | 11 | 11 | 11 | 11 140421237831424_101 | 10422 | finsh | 1 | 0 | 0 | 0 | 0 140421237831424_101 | 16771 | init | 1 | 0 | 0 | 0 | 0 140421237831424_101 | 16771 | package | 1 | 103 | 103 | 103 | 103 140421237831424_101 | 16771 | spictx | 1 | 1 | 1 | 1 | 1 140421237831424_101 | 16771 | compile | 1 | 1869 | 1869 | 1869 | 1869 140421237831424_101 | 16771 | exec_context | 1 | 3 | 3 | 3 | 3 140421237831424_101 | 16771 | execute | 1 | 24011 | 24011 | 24011 | 24011 140421237831424_101 | 16771 | exec_cursor | 1 | 1 | 1 | 1 | 1 140421237831424_101 | 16771 | cleanup | 1 | 16 | 16 | 16 | 16 140421237831424_101 | 16771 | finsh | 1 | 1 | 1 | 1 | 1 (18 rows) gaussdb=# SELECT dbe_profiler.pl_clear_profiling(''); gaussdb=# SELECT * FROM dbe_profiler.pl_profiling_functions; run_id | funcoid | schema | funcname | total_occur | total_time --------+---------+--------+----------+-------------+------------ (0 rows) gaussdb=# DROP TABLE t2;

包含的接口和系统表 高级功能包DBE_PROFILER支持的所有接口请参见表1 DBE_PROFILER。 表1 DBE_PROFILER 接口名称 描述 DBE_PROFILER.PL_START_PLPROFILING 允许用户对目标存储过程进行profiling。 DBE_PROFILER.PL_CLEAR_PROFILING 删除某次或所有profiling后储存在系统表里的数据。 DBE_PROFILER.PL_START_PLPROFILING 允许用户对目标存储过程进行profiling。DBE_PROFILER.PL_START_PLPROFILING函数原型为： 1 DBE_PROFILER.PL_START_PLPROFILING (run_id varchar2(64)) return void; 表2 DBE_PROFILER.PL_START_PLPROFILING接口参数说明 参数 描述 run_id 表示此次profiling的执行编号，系统会将用户的session_id和执行编号拼接为形如sessionid_runid的字符串写入表中，作为本次profiling的唯一标识。 DBE_PROFILER.PL_CLEAR_PROFILING 删除某次或所有profiling后储存在系统表里的数据。DBE_PROFILER.PL_CLEAR_PROFILING函数原型为： 1 DBE_PROFILER.PL_CLEAR_PROFILING (run_id varchar2) return void; 表3 DBE_PROFILER.PL_CLEAR_PROFILING接口参数说明 参数 描述 run_id 非空值时，表示删除某次profiling数据的唯一标识；为空值时，表示删除所有profiling后的数据。

约束 dbe_profiler.pl_start_profiling不支持在存储过程内使用，在存储过程内调用不生效。 dbe_profiler.pl_start_profiling不支持事务失败记录统计信息到系统表。 dbe_profiler.pl_start_profiling入参runid长度限制为64，超长将会报错。 dbe_profiler.pl_start_profiling入参如果和profiler系统表内的runid重复将会报错。 plprofiler不支持匿名块语句、PACKAGE的初始化语句和嵌套子程序内的语句。 自治事务的提交和回滚不会影响主事务已提交的数据，因此plprofiler暂不支持记录包含自治事务的存储过程的信息。

概述 在PL/SQL函数和存储过程中查找性能问题可能会很困难。在系统或扩展视图中唯一可见的是从客户端发送的查询。在调用存储过程的情况下，这只是最外层的存储过程调用。plprofiler扩展可用于快速识别最耗时的存储过程，然后向下查看其中的单个语句耗时情况。 使用此工具，可以在会话中先创建存储过程及相关表信息，然后调用plprofiler接口对存储过程进行profiling，再执行存储过程，此时存储过程分析数据已生成。可以通过查询系统表去获取数据。表5 DBE_PROFILER.PL_PROFILING_FUNCTIONS可以查看此次profiling涉及的存储过程。 表6 DBE_PROFILER.PL_PROFILING_DETAILS查看存储过程内每条语句的执行时间细节。表7 DBE_PROFILER.PL_PROFILING_CALLGRAPH查看调用栈信息和对应每个存储过程执行的整体时间。表8 DBE_PROFILER.PL_PROFILING_TRACKINFO查看存储过程每个阶段的执行时间。可以通过接口DBE_PROFILER.PL_CLEAR_PROFILING去删除某次或所有profiling后储存在系统表里的数据。 dbe_profiler工具的原理是在执行pl_start_profiling后，系统会初始化内存以准备记录数据，然后对后续执行的存储过程进行打桩，在关键点记录详细信息，并将这些信息记录在内存中，等待事务提交之后才会将内存中的数据写入四张系统表。在事务中执行dbe_profiler工具时须注意，在事务执行阶段，由于事务未提交，所以内存中的数据不会写入系统表中，只有在执行commit后才会将数据写入系统表。同理，执行rollback后，会将所有数据进行清理。

接口介绍 高级功能包DBE_RANDOM支持的所有接口请参见表 DBE_RANDOM接口参数说明。 表1 DBE_RANDOM接口参数说明 接口名称 描述 DBE_RANDOM.SET_SEED 设置一个随机数的种子。 DBE_RANDOM.GET_VALUE 生成一个大小介于指定的low及high之间的随机数。 DBE_RANDOM.SET_SEED 存储过程SEED用于设置一个随机数的种子。DBE_RANDOM.SET_SEED函数原型为： 1 DBE_RANDOM.SET_SEED (seed IN INTEGER); 表2 DBE_RANDOM.SET_SEED接口参数说明 参数 描述 seed 用于产生一个随机数的种子。 DBE_RANDOM.GET_VALUE 函数GET_VALUE生成一个大小介于指定的low及high之间的随机数。DBE_RANDOM.GET_VALUE函数原型为： 1 2 3 4 DBE_RANDOM.GET_VALUE( min IN NUMBER default 0, max IN NUMBER default 1) RETURN NUMBER; 表3 DBE_RANDOM.GET_VALUE接口参数说明 参数 描述 min 指定随机数大小的下边界，生成的随机数大于或等于min。 max 指定随机数大小的上边界，生成的随机数小于max。 实际上，只要求这里的参数类型是NUMERIC即可，对于左右边界的大小并没有要求。 DBE_RANDOM实现的是伪随机，所以若使用的初值（种子）不变，那么伪随机数的数序也不变，使用时需要注意。 生成的随机数有效数字为15位。