目录
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');
/