DBMS_UTILITY內置包提供了多種工具類子程序。
BMS_UTILITY子程序總覽
子程序 | 說明 |
ANALYZE_DATABASE Procedure | 分析數據庫中的表。 |
ANALYZE_SCHEMA Procedure | 分析schema中的表。 |
ANALYZE_PART_OBJECT Procedure | 分析單張表。 |
CANONICALIZE Procedure | 規范化給定的字符串。 |
COMMA_TO_TABLE Procedure | 將逗號分隔的名稱標識符列表轉換為名稱表。 |
DB_VERSION Procedure | 獲取數據庫版本。 |
EXEC_DDL_STATEMENT Procedure | 執行DDL語句。 |
FORMAT_CALL_STACK Function | 格式化當前調用棧。 |
FORMAT_ERROR_BACKTRACE Function | 格式化從當前的錯誤點到捕獲錯誤的異常處理程序的堆棧信息。 |
FORMAT_ERROR_STACK Function | 格式化當前錯誤棧。 |
GET_CPU_TIME Function | 返回當前的CPU時間(以百分之一秒為單位)。 |
GET_DEPENDENCY Procedure | 顯示傳入對象的依賴關系。 |
GET_HASH_VALUE Function | 計算給定字符串的哈希值。 |
GET_PARAMETER_VALUE Function | 獲取數據庫初始化參數設置。 |
GET_TIME Function | 返回當前的時鐘時間(以百分之一秒為單位)。 |
NAME_TOKENIZE Procedure | 將給定名稱解析為其組成部分。 |
TABLE_TO_COMMA Procedure | 將名稱標識符的表轉為逗號分隔的列表。 |
DBMS_UTILITY數據類型
LNAME_ARRAY
LNAME_ARRAY用于存儲長名稱(包括完全限定名稱)的列表。
TYPE LNAME_ARRAY IS TABLE OF VARCHAR2(4000);
UNCL_ARRAY
UNCL_ARRAY用于存儲名稱標識符的列表。
TYPE UNCL_ARRAY IS TABLE OF VARCHAR2(227);
ANALYZE_DATABASE
該存儲過程用于分析數據庫中的表。
語法
DBMS_UTILITY.ANALYZE_DATABASE (
method IN VARCHAR2,
estimate_rows IN INTEGER DEFAULT NULL,
estimate_percent IN INTEGER DEFAULT NULL,
method_opt IN VARCHAR2 DEFAULT NULL);
參數說明
參數 | 說明 |
method | 指定ANALYZE的方法。取值如下:
COMPUTE 和 ESTIMATE之間沒有差異,都是執行ANALYZE語句。其他參數均為兼容性提供參數,執行時會被忽略。 |
estimate_rows | (可選參數)估計統計信息所依據的行數。 |
estimate_percent | (可選參數)估計統計信息所依據的行百分比。 |
method_opt | (可選參數)分析的對象類型。 |
示例
CALL DBMS_UTILITY.ANALYZE_DATABASE('COMPUTE');
ANALYZE_SCHEMA
該存儲過程用于分析schema中的表。
語法
DBMS_UTILITY.ANALYZE_SCHEMA (
schema IN VARCHAR2,
method IN VARCHAR2,
estimate_rows IN INTEGER DEFAULT NULL,
estimate_percent IN INTEGER DEFAULT NULL,
method_opt IN VARCHAR2 DEFAULT NULL);
參數說明
參數 | 說明 |
schema | schema的名稱。 |
method | 指定ANALYZE的方法。取值如下:
COMPUTE和ESTIMATE之間沒有差異,都是執行ANALYZE語句。除去schema和method以外的參數均為兼容性提供參數,執行時會被忽略。 |
estimate_rows | (可選參數)估計統計信息所依據的行數。 |
estimate_percent | (可選參數)估計統計信息所依據的行百分比。 |
method_opt | (可選參數)分析的對象類型。 |
示例
CALL DBMS_UTILITY.ANALYZE_SCHEMA('public', 'compute');
ANALYZE_PART_OBJECT
該存儲過程用于分析單張表。
語法
DBMS_UTILITY.ANALYZE_PART_OBJECT (
schema IN VARCHAR2 DEFAULT NULL,
object_name IN VARCHAR2 DEFAULT NULL,
object_type IN CHAR DEFAULT 'T',
command_type IN CHAR DEFAULT 'E',
command_opt IN VARCHAR2 DEFAULT NULL,
sample_clause IN VARCHAR2 DEFAULT 'sample 5 percent ');
參數說明
參數 | 說明 |
schema | 待分析對象的schema名稱。 |
object_name | 待分析對象。 |
object_type | (可選參數)待分析對象類型。 |
command_type | (可選參數)需要執行的分析功能類型。 |
command_opt | (可選參數)command_type使用的可選值。 |
sample_clause | (可選參數)command_type為 |
除了schema和object_name,其他參數均為兼容性提供參數,執行時會被忽略。
示例
CALL DBMS_UTILITY.analyze_part_object('public', 'table2');
CANONICALIZE
該存儲過程用于規范化一個給定的字符串。
語法
DBMS_UTILITY.CANONICALIZE(
name IN VARCHAR2,
canon OUT VARCHAR2,
canon_len IN INTEGER);
參數說明
參數 | 說明 |
name | 待規范化的字符串。 |
canon | 完成規范化的字符串。 |
canon_len | name中從第一個字符開始待規范化的字節數量。 |
示例
該示例展示了如何規范化一個給定的字符串。
DECLARE
name varchar2 default 'aBc."dEf"."ghi"';
length integer default 50;
canon varchar2;
BEGIN
DBMS_UTILITY.CANONICALIZE(name,canon,length);
DBMS_OUTPUT.PUT_LINE(canon);
END;
-- "ABC"."dEf"."ghi"
COMMA_TO_TABLE
該存儲過程用于將逗號分隔的名稱列表轉換為名稱表。
語法
DBMS_UTILITY.COMMA_TO_TABLE (
list IN VARCHAR2,
tablen OUT INTEGER,
tab OUT UNCL_ARRAY);
參數說明
參數 | 說明 |
list | 以逗號分隔的名稱標識符列表。 |
tablen | tab中的條目數量。 |
tab | 包含list中的各個名稱的表。 |
示例
該示例展示了如何將逗號分隔的名稱列表轉換為名稱表。
DECLARE
lname DBMS_UTILITY.LNAME_ARRAY;
length integer;
list varchar2;
BEGIN
list := 'a.b.c.d , b , c , select1';
DBMS_UTILITY.COMMA_TO_TABLE(list,length,lname);
FOR i IN 1..length LOOP
DBMS_OUTPUT.PUT_LINE('-> ' || lname(i) || '<- ' || length(lname(i)));
END LOOP;
DBMS_OUTPUT.PUT_LINE('-- finished --');
END;
-> a.b.c.d <- 8
-> b <- 3
-> c <- 3
-> select1 <- 8
-- finished --
DB_VERSION
該存儲過程用于獲取數據庫的版本信息。
語法
DBMS_UTILITY.DB_VERSION (
version OUT VARCHAR2,
compatibility OUT VARCHAR2);
參數說明
參數 | 說明 |
version | 數據庫版本。 |
compatibility | 數據庫兼容性設置(忽略)。 |
示例
該示例展示了如何獲取數據庫的版本信息。
DECLARE
version varchar2(100);
compatibility varchar2(100);
BEGIN
DBMS_UTILITY.DB_VERSION(version, compatibility);
DBMS_OUTPUT.PUT_LINE(version);
DBMS_OUTPUT.PUT_LINE(compatibility);
END;
-- PostgreSQL 14.8 (PolarDB 14.8.10.0 build 0d3bf26c debug)
-- PostgreSQL 14.8 (PolarDB 14.8.10.0 build 0d3bf26c debug)
EXEC_DDL_STATEMENT
該存儲過程用于執行DDL語句。
語法
DBMS_UTILITY.EXEC_DDL_STATEMENT (
parse_string IN VARCHAR2);
參數說明
參數 | 說明 |
parse_string | 待執行的DDL語句。 |
示例
該示例展示了如何通過該存儲過程執行DDL語句。
CALL DBMS_UTILITY.EXEC_DDL_STATEMENT('CREATE TABLE test(a int, b varchar2(20))');
SELECT * FROM test;
a | b
---+---
(0 rows)
FORMAT_CALL_STACK
該函數用于格式化當前的調用棧。
語法
DBMS_UTILITY.FORMAT_CALL_STACK();
RETURN VARCHAR2;
返回值
返回值 | 說明 |
VARCHAR2 | 格式化后的調用棧信息。 |
示例
該示例展示了如何輸出當前的調用棧的格式化信息。
CREATE FUNCTION func() RETURNS varchar2
IS
BEGIN
return dbms_utility.format_call_stack();
END;
select * from func();
func
--------------------------------------------------
----- PL/SQL Call Stack ----- +
object line object +
handle number name +
0 2 function format_call_stack()+
17089 2 function func()
(1 row)
FORMAT_ERROR_BACKTRACE
該函數用于格式化從當前的錯誤點到捕獲錯誤的異常處理程序的堆棧信息。
語法
DBMS_UTILITY.FORMAT_ERROR_BACKTRACE()
RETURN VARCHAR2;
返回值
返回值 | 說明 |
VARCHAR2 | 回溯的堆棧信息。 |
示例
該示例創建了一個函數的調用鏈,被調用函數拋出異常,調用方捕獲異常,并通過FORMAT_ERROR_BACKTRACE
打印錯誤堆棧信息。
CREATE FUNCTION inner(a integer) RETURNS integer
IS
DECLARE
res integer;
BEGIN
res = a/0;
RETURN res;
EXCEPTION
WHEN others THEN
RAISE EXCEPTION 'expected exception';
END;
CREATE FUNCTION outer() RETURNS integer
IS
BEGIN
return inner(100);
EXCEPTION
WHEN others THEN
DBMS_OUTPUT.PUT_LINE(DBMS_UTILITY.FORMAT_ERROR_BACKTRACE());
return -1;
END;
SELECT outer() FROM dual;
----- Error Stack -----
ERR-33816706: division by zero
PL/SQL function "inner"(integer) line 4 at assignment
PL/SQL function "outer"() line 2 at RETURN
ERR-16777248: expected exception
PL/SQL function "inner"(integer) line 8 at RAISE
PL/SQL function "outer"() line 2 at RETURN
FORMAT_ERROR_STACK
該函數用于格式化當前的錯誤棧。
語法
DBMS_UTILITY.FORMAT_ERROR_STACK
RETURN VARCHAR2;
返回值
返回值 | 說明 |
VARCHAR2 | 格式化后的錯誤調用棧信息。 |
示例
該示例創建了一個函數的調用鏈,被調用函數拋出異常,調用方捕獲異常,并通過FORMAT_ERROR_STACK
打印錯誤棧信息。
CREATE FUNCTION inner(a integer) RETURNS integer
IS
DECLARE
res integer;
BEGIN
res = a/0;
RETURN res;
EXCEPTION
WHEN others THEN
RAISE EXCEPTION 'expected exception';
END;
CREATE FUNCTION outer() RETURNS integer
IS
BEGIN
return inner(100);
EXCEPTION
WHEN others THEN
DBMS_OUTPUT.PUT_LINE(DBMS_UTILITY.FORMAT_ERROR_STACK());
return -1;
END;
SELECT outer() FROM dual;
----- Error Stack -----
ERR-33816706: division by zero
PL/SQL function "inner"(integer) line 4 at assignment
PL/SQL function "outer"() line 2 at RETURN
ERR-16777248: expected exception
PL/SQL function "inner"(integer) line 8 at RAISE
PL/SQL function "outer"() line 2 at RETURN
GET_CPU_TIME
該函數用于返回當前的CPU時間。
語法
DBMS_UTILITY.GET_CPU_TIME
RETURN INTEGER;
返回值
返回值 | 說明 |
INTEGER | 任意時間點的CPU時間(百分之一秒為單位)。 |
示例
該示例展示了在程序sleep前后的CPU時間(兩個CPU時間的差值遠小于程序的sleep時間)。
BEGIN
DBMS_OUTPUT.PUT_LINE('start cpu time:' || DBMS_UTILITY.GET_CPU_TIME());
-- start cpu time:11
DBMS_SESSION.SLEEP(5);
DBMS_OUTPUT.PUT_LINE('end cpu time:' || DBMS_UTILITY.GET_CPU_TIME());
-- end cpu time:11
END;
GET_DEPENDENCY
該存儲過程用于顯示傳入對象的依賴關系。
語法
DBMS_UTILITY.GET_DEPENDENCY
type IN VARCHAR2,
schema IN VARCHAR2,
name IN VARCHAR2);
參數說明
參數 | 說明 |
type | name的對象類型。 |
schema | name所在的schema的名稱。 |
name | 待獲取依賴項的對象的名稱。 |
示例
該示例創建了一張表,并在此基礎上創建了一張視圖,通過該存儲過程查看該視圖的依賴關系。
CREATE TABLE t(a int, b int);
CREATE VIEW v AS SELECT a, b FROM t;
CALL DBMS_UTILITY.GET_DEPENDENCY('view','public','v');
-- TABLE T
GET_HASH_VALUE
該函數用于計算給定字符串的哈希值。
語法
DBMS_UTILITY.GET_HASH_VALUE (
name VARCHAR2,
base INTEGER,
hash_size INTEGER)
RETURN INTEGER;
參數說明
參數 | 說明 |
name | 待計算哈希值的字符串。 |
base | 返回的哈希值的起始基值。 |
hash_size | 返回的哈希值的范圍。 |
返回值
返回值 | 說明 |
INTEGER | 生成的哈希值。 |
示例
該示例展示了如何計算給定字符串的哈希值(該示例計算給定字符串在1到99內的哈希值)。
SELECT DBMS_UTILITY.GET_HASH_VALUE('PolarDB', 1, 100) FROM dual;
get_hash_value
----------------
67
(1 row)
GET_PARAMETER_VALUE
該函數用于獲取數據庫初始化參數設置。
語法
DBMS_UTILITY.GET_PARAMETER_VALUE (
parnam IN VARCHAR2,
intval OUT INTEGER,
strval OUT VARCHAR2)
RETURN INTEGER;
參數說明
參數 | 說明 |
parnam | 需要返回其值的參數的名稱。pg_settings系統視圖中列出了這些參數。 |
intval | 整數參數的值或strval的長度。 |
strval | 字符串參數的值。 |
返回值
返回值 | 說明 |
INTEGER | 如果參數值為INTEGER,返回0。否則返回1。 |
示例
該示例展示了通過該函數獲取字符串和整數類型的參數。
DECLARE
intval INTEGER;
strval VARCHAR2(80);
ret INTEGER;
BEGIN
ret := DBMS_UTILITY.GET_PARAMETER_VALUE('client_encoding', intval, strval);
DBMS_OUTPUT.PUT_LINE('ret is: ' || ret || '; intval is: ' || intval || '; strval is: ' || strval);
ret := DBMS_UTILITY.GET_PARAMETER_VALUE('block_size', intval, strval);
DBMS_OUTPUT.PUT_LINE('ret is: ' || ret || '; intval is: ' || intval || '; strval is: ' || strval);
END;
ret is: 1; intval is: 4; strval is: UTF8
ret is: 0; intval is: 8192; strval is:
GET_TIME
該函數用于返回當前的時間。
語法
DBMS_UTILITY.GET_TIME
RETURN INTEGER;
返回值
返回值 | 說明 |
INTEGER | 任意時間點的時鐘時間(百分之一秒為單位)。 |
示例
該示例展示了通過GET_TIME獲取程序執行前后的時間差。
DECLARE
start_time integer;
end_time integer;
BEGIN
start_time := DBMS_UTILITY.GET_TIME;
DBMS_LOCK.SLEEP(5);
end_time := DBMS_UTILITY.GET_TIME;
DBMS_OUTPUT.PUT_LINE('total time is:' || end_time - start_time);
END;
NAME_TOKENIZE
該存儲過程用于將給定名稱解析為其組成部分。
語法
DBMS_UTILITY.NAME_TOKENIZE (
name IN VARCHAR2,
a OUT VARCHAR2,
b OUT VARCHAR2,
c OUT VARCHAR2,
dblink OUT VARCHAR2,
nextpos OUT INTEGER);
參數說明
參數 | 說明 |
name | 輸入的名稱。由SQL標識符組成,格式為a [ . b [ . c ] ] [ @ dblink ]。 |
a | name中的第一個標識符。 |
b | name中的第二個標識符。 |
c | name中的第三個標識符。 |
dblink | name中的dblink部分。 |
nextpos | 完成輸入name解析后的下一個字符位置 |
示例
該示例展示了如何通過該存儲過程進行名稱的解析。
DECLARE
a varchar2;
b varchar2;
c varchar2;
dblink varchar2;
nextpos integer;
name varchar2;
BEGIN
name := 'sch.tbl@dblink';
DBMS_UTILITY.NAME_TOKENIZE(name, a, b, c, dblink, nextpos);
DBMS_OUTPUT.PUT_LINE('name : ' || name);
DBMS_OUTPUT.PUT_LINE('a : ' || a);
DBMS_OUTPUT.PUT_LINE('b : ' || b);
DBMS_OUTPUT.PUT_LINE('c : ' || c);
DBMS_OUTPUT.PUT_LINE('dblink : ' || dblink);
DBMS_OUTPUT.PUT_LINE('nextpos: ' || nextpos);
END;
name : sch.tbl@dblink
a : SCH
b : TBL
c :
dblink : DBLINK
nextpos: 14
TABLE_TO_COMMA
該存儲過程用于將名稱標識符的表轉為逗號分隔的列表。
語法
DBMS_UTILITY.TABLE_TO_COMMA (
tab IN UNCL_ARRAY,
tablen OUT INTEGER,
list OUT VARCHAR2);
參數說明
參數 | 說明 |
tab | 包含名稱標識符的表。 |
tablen | tab中的條目數量。 |
list | 以逗號分隔的名稱列表。 |
示例
該示例展示了如何將包含名稱的表轉為逗號分隔的形式。
DECLARE
result varchar2;
length integer;
list dbms_utility.lname_array;
BEGIN
list := dbms_utility.lname_array('name1', 'name2', 'name3');
DBMS_UTILITY.TABLE_TO_COMMA(list, length, result);
DBMS_OUTPUT.PUT_LINE('result is: ' || result || '; length is: ' || length );
END;
-- result is: name1,name2,name3; length is: 3