diff --git a/CN/modules/ROOT/pages/master/compatibility_features_design/dbms_output_impl.adoc b/CN/modules/ROOT/pages/master/compatibility_features_design/dbms_output_impl.adoc new file mode 100644 index 00000000..6838ae66 --- /dev/null +++ b/CN/modules/ROOT/pages/master/compatibility_features_design/dbms_output_impl.adoc @@ -0,0 +1,14 @@ +:sectnums: +:sectnumlevels: 5 + += DBMS_OUTPUT 实现 + +== 会话输出 + +`contrib/ivorysql_ora/src/builtin_packages/dbms_output/dbms_output--1.0.sql` 中的 PL/iSQL 包调用对应的 C 函数存取消息。缓冲区保存在当前会话的后端中。写入操作先将文本追加到待完成的行,再在结束该行时将它放入可读缓冲区。 + +== 读取完整行 + +C 读取函数返回复合结果。包将行和状态复制到 `GET_LINE` 的输出参数中,或将数组和行数复制到 `GET_LINES` 的参数中。读取完整行后,读取位置向前推进。应用可自行选择如何显示或处理返回的文本。 + +可运行的示例见 xref:master/oracle_compatibility/compat_dbms_output.adoc[DBMS_OUTPUT 包]。 diff --git a/CN/modules/ROOT/pages/master/oracle_compatibility/compat_dbms_output.adoc b/CN/modules/ROOT/pages/master/oracle_compatibility/compat_dbms_output.adoc new file mode 100644 index 00000000..a2a68e87 --- /dev/null +++ b/CN/modules/ROOT/pages/master/oracle_compatibility/compat_dbms_output.adoc @@ -0,0 +1,34 @@ +:sectnums: +:sectnumlevels: 5 + += DBMS_OUTPUT 包 + +== 缓冲和读取消息 + +请用具有包执行权限的角色连接 Oracle 兼容模式。`DBMS_OUTPUT.ENABLE` 启用会话缓冲区。`PUT` 将文本追加到当前行,`PUT_LINE` 追加文本并结束当前行,`NEW_LINE` 直接结束当前行。 + +在同一会话中使用 `GET_LINE` 读取已完成的行。成功读到一行时,输出状态为 0。缓冲区为空时,状态为 1。需要一次读取多行时,可使用 `GET_LINES`。 + +[source,sql] +---- +CALL dbms_output.enable(20000); +CALL dbms_output.put('invoice='); +CALL dbms_output.put_line('42'); + +DECLARE + output_line text; + status integer; +BEGIN + dbms_output.get_line(output_line, status); + RAISE NOTICE 'status=% line=%', status, output_line; + dbms_output.get_line(output_line, status); + RAISE NOTICE 'status=%', status; +END; +/ + +CALL dbms_output.disable(); +---- + +第一条通知显示 `status=0 line=invoice=42`。第二条通知显示 `status=1`,因为第一次读取已经取走了唯一的完整行。`DISABLE` 会关闭缓冲并清空缓冲区。 + +实现细节见 xref:master/compatibility_features_design/dbms_output_impl.adoc[DBMS_OUTPUT 实现]。 diff --git a/EN/modules/ROOT/pages/master/compatibility_features_design/dbms_output_impl.adoc b/EN/modules/ROOT/pages/master/compatibility_features_design/dbms_output_impl.adoc new file mode 100644 index 00000000..b38bc5bb --- /dev/null +++ b/EN/modules/ROOT/pages/master/compatibility_features_design/dbms_output_impl.adoc @@ -0,0 +1,14 @@ +:sectnums: +:sectnumlevels: 5 + += DBMS_OUTPUT Implementation + +== Per-session output + +The PL/iSQL package in `contrib/ivorysql_ora/src/builtin_packages/dbms_output/dbms_output--1.0.sql` delegates storage and retrieval to the corresponding C functions. The backend keeps the buffer for the session. Writers append fragments to the pending line, then move the line into the readable buffer when it is finished. + +== Read completed lines + +The C retrieval functions return a composite result. The package copies the line and status into `GET_LINE` output parameters, or an array and count into `GET_LINES` parameters. The reader advances as it consumes completed lines. Applications choose how to display or process the returned text. + +See xref:master/oracle_compatibility/compat_dbms_output.adoc[DBMS_OUTPUT package] for a runnable example. diff --git a/EN/modules/ROOT/pages/master/oracle_compatibility/compat_dbms_output.adoc b/EN/modules/ROOT/pages/master/oracle_compatibility/compat_dbms_output.adoc new file mode 100644 index 00000000..d19d54f4 --- /dev/null +++ b/EN/modules/ROOT/pages/master/oracle_compatibility/compat_dbms_output.adoc @@ -0,0 +1,34 @@ +:sectnums: +:sectnumlevels: 5 + += DBMS_OUTPUT Package + +== Buffer and read messages + +Connect in Oracle compatibility mode with a role that can execute the package. `DBMS_OUTPUT.ENABLE` enables a session buffer. `PUT` appends text to the current line, `PUT_LINE` appends text and finishes the line, and `NEW_LINE` finishes the line without appending text. + +Use `GET_LINE` to read each completed line in the same session. Its output status is 0 when it retrieves a line and 1 when the buffer is empty. Use `GET_LINES` when a caller needs to retrieve several lines at once. + +[source,sql] +---- +CALL dbms_output.enable(20000); +CALL dbms_output.put('invoice='); +CALL dbms_output.put_line('42'); + +DECLARE + output_line text; + status integer; +BEGIN + dbms_output.get_line(output_line, status); + RAISE NOTICE 'status=% line=%', status, output_line; + dbms_output.get_line(output_line, status); + RAISE NOTICE 'status=%', status; +END; +/ + +CALL dbms_output.disable(); +---- + +The first notice shows `status=0 line=invoice=42`. The second shows `status=1`, because the first call consumed the only completed line. `DISABLE` turns buffering off and clears the buffer. + +See xref:master/compatibility_features_design/dbms_output_impl.adoc[DBMS_OUTPUT implementation].