金仓数据库 KingbaseES 插件DBMS_OUTPUT

目录

1. 概述

2. 限制

3. 启用

4. 禁用

5. DBMS_OUTPUT系统包支持向缓冲区输入信息

6. DBMS_OUTPUT系统包支持从缓冲区中获取信息

7. DBMS_OUTPUT系统包支持客户端显示缓冲区信息

---

1. 概述

DBMS_OUTPUT系统包可以提供将文本行写入缓冲区、供以后提取和显示的功能。主要用于调试PL/SQL程序，或者在Ksql客户端命令中显示信息和报表，譬如我们可以写一个简单的匿名pl/sql程序块，而该块出于某种目的可以使用此包来显示一些信息。
DBMS_OUTPUT系统包不支持PG模式。

 

2. 限制

DBMS_OUTPUT行和缓冲区大小的限制：

• 最大行大小为32767字节。
• 默认缓冲区大小为20000字节。最小为2000字节，最大是无限的。

3. 启用

语法格式：

DBMS_OUTPUT.ENABLE(buffer_size IN INTEGER DEFAULT 20000);

功能描述：

这个过程允许调用PUT、PUT_LINE、NEW_LINE、GET_LINE和GET_LINES等过程。

参数说明：

buffer_size:缓冲区最大尺寸为1000000字节，最小为2000字节，默认为20000字节。将buffer_size设置为null，缓冲区大小将没有限制。

使用说明：

• 如果没有激活DBMS_OUTPUT包，对这些过程的调用将被忽略。
• 如果有多个调用要启用，那么buffer_size将以最后指定的值。
• 当set serveroutput on开启时可以不用调用enable和disable过程。
• 缓存区设定大小的范围为2000至1000000，如果buffer_size的值小于2000，则为2000；如果buffer_size的值超过1000000，则为1000000；如果输入缓存区的数据大小超过缓存区设定的最大值，将直接报错。

示例：

call dbms_output.enable();
call dbms_output.enable(NULL);
call dbms_output.enable(3000);

4. 禁用

语法格式：

DBMS_OUTPUT.DISABLE();

功能描述：

此过程禁用对PUT、PUT_LINE、NEW_LINE、GET_LINE和GET_LINES等过程的调用，并清空缓冲区。

使用说明：

• 如果该DBMS_OUTPUT包被禁用了，那么所有对其子程序(subprogram)的调用都将被忽略。这样用户可以设计应用程序，仅在客户端程序能够处理这些信息的时候启用这些子程序。
• 如果set serveroutput off时调用了disable过程，下次调用其他过程，必须调用enable过程。

5. DBMS_OUTPUT系统包支持向缓冲区输入信息

5.1. 向缓冲区中追加内容
语法格式：

DBMS_OUTPUT.PUT(item IN VARCHAR2);

功能描述：

该过程用来追加部分内容到Buffer中的最后一行。

使用说明：

• 当追加内容时可以使用put过程输入，如需整行方式输入最好使用put_line过程。
• 若单行长度超过限制那么将报错，或输入数据超过缓存区设定值将报错。
• 注意在调用PUT或PUT_LINE的PL/SQL程序单元结束之前，对PUT或PUT_LINE指定的内容不会输出。
• 当调用PUT_LINE过程时将自动加入换行符，若使用PUT来构建行，那么必须手动使用NEW_LINE过程来加入换行符。GET_LINE和GET_LINES过程不会返回没有以换行符终结的一行。

示例：

set serveroutput on
\set SQLTERM /
begin
    dbms_output.put('test1');
    dbms_output.new_line();
    dbms_output.put('test2');
end;
/

5.2. 向缓冲区追加单行信息
语法格式：

DBMS_OUTPUT.PUT_LINE(item IN VARCHAR2);

功能描述：

该存储过程用来向Buffer中新添一行信息。

使用说明：

• 输入数据超过缓存区设定值将报错。
• GET_LINE和GET_LINES不返回未使用换行符终止的行。

示例：

set serverout on
call dbms_output.put_line('hi' || chr(10) || 'hello'||chr(10) || '
world');
/

5.3. 向缓冲区追加新行
语法格式：

DBMS_OUTPUT.NEW_LINE();

功能描述：

该存储过程向缓冲区添加一个换行符，产生新一行。

使用说明：

• 每调用一次生成一次新行。

示例：

set serverout on
begin
    dbms_output.put('test1');
    dbms_output.new_line();
    dbms_output.put('test2');
    dbms_output.new_line();
    dbms_output.new_line();
    dbms_output.put_line('test3');
end;
/

6. DBMS_OUTPUT系统包支持从缓冲区中获取信息

6.1. 获取首行信息
语法格式：

DBMS_OUTPUT.GET_LINE(line OUT VARCHAR2, status OUT INTEGER);

功能描述：

该过程从buffer中获取单行信息，先加入的信息先获取，获取后buffer中的此信息将被删除。
参数和返回值使用说明：

• line：将获取buffer中的一行信息，但不包括最后的换行符。
• status：若调用成功则返回0，调用失败则返回1。

使用说明：

调用GET_LINE或GET_LINES成功获取内容后，在下一次调用PUT， PUT_LINE or NEW_LINE过程前没有被获取的缓存都将被丢弃，以避免误会。

示例：

set serverout on
\set SQLTERM /
declare
    line varchar2(120);
    status integer;
begin
    dbms_output.put('hello');
    dbms_output.put_line('world');
    dbms_output.get_line(line, status);
    dbms_output.put_line(line || status);
end;
/

6.2. 获取多行信息
语法格式：

PROCEDURE get_lines(lines OUT CHARARR, numlines IN OUT integer);
PROCEDURE get_lines(lines OUT DBMSOUTPUT_LINESARRAY, numlines IN OUT
integer);

功能描述：

该存储过程用以从Buffer中获取一个多行的的数组，获取后buffer中的此信息将被删除。
参数和返回值说明：

• CHARARR(包内类型)：TYPE CHARARR IS TABLE OF VARCHAR2(32767) INDEX BY INT;
• DBMSOUTPUT_LINESARRAY(包外类型)：TYPE DBMSOUTPUT_LINESARRAY IS VARRAY(2147483647) OF VARCHAR2(32767);
• lines：返回缓冲信息的行数组。数组中每一行的最大长度为32767字节。
• numlines：当缓存区行数多于或等于检索的行数时，返回检索行数；当缓存区行数少于检索的行数时，返回缓存区行数。

使用说明：

• 在获取信息之后，若下次调用输入过程，则没有检索到的任何行都将被丢弃，以避免与下一条消息混淆。
• CHARARR类型numlines参数：当不指定参数或此参数小于等于0，不获取内容，并返回numlines为0；当此参数大于0，如果缓存区行数多于或等于检索的行数时，返回检索行数；如果缓存区行数少于检索的行数时，返回缓存区行数。
• DBMSOUTPUT_LINESARRAY类型numlines参数：当不指定参数，默认获取全部内容，并返回numlines为获取行数；当此参数小于0，将报错；当参数大于等于0时，如果缓存区行数多于或等于检索的行数时，返回检索行数，当缓存区行数少于检索的行数时，返回缓存区行数。

示例：

set serverout on
DECLARE
    v_data  dbms_output.CHARARR;
    numlines integer := 2;
BEGIN
    dbms_output.put_line('TEST 1');
    dbms_output.put_line('TEST 2');
    dbms_output.put_line('TEST 3');
    dbms_output.get_lines(v_data, numlines);
    dbms_output.put_line(v_data(1));
    dbms_output.put_line(v_data(2));
end;
/
DECLARE
    v_data  DBMSOUTPUT_LINESARRAY;
    numlines integer := 2;
BEGIN
    dbms_output.put_line('TEST 1');
    dbms_output.put_line('TEST 2');
    dbms_output.get_lines(v_data, numlines);
    dbms_output.put_line(numlines);
    dbms_output.put_line(v_data(1));
    dbms_output.put_line(v_data(2));
end;
/

7. DBMS_OUTPUT系统包支持客户端显示缓冲区信息

7.1. 客户端命令启动输出功能
语法格式：

set serverout[put] on[;]

功能描述：

• 启用DBMS_OUTPUT系统包功能。
• 缓存大小设为不限制大小。
• 能代替enable过程，即可以不需要enable过程。
• 客户端输出缓存区消息。

使用说明：

set serverout[put]跟‘on’或‘on;’，当输入无关命令时会提示命令错误。

示例：

set serverout on
create or replace procedure protest_A_1 is
begin
  dbms_output.put_line('....test1');
  dbms_output.put_line('....test2');
end;
/
declare
  v_status integer := 0;
  v_data varchar2(100);
begin
  protest_A_1();
  dbms_output.put_line('test3');
  dbms_output.get_line(v_data, v_status);
  dbms_output.put_line('v_data: ' ||v_data || 'v_status: ' ||v_status);
  dbms_output.put_line('test4');
end;
/

7.2. 客户端命令禁用输出功能
语法格式：

set serverout[put] off[;]

功能描述：

• 禁用DBMS_OUTPUT系统包功能。
• 清除缓存。
• 能代替disable过程，即可以不需要disable过程。

使用说明：

set serverout[put]跟‘off’或‘off;’，当输入无关命令时会提示命令错误。

示例：

set serverout off
call dbms_output.put_line('hi' || chr(10) || 'hello'||chr(10) || '
world');
/