From 4e287967757f2d0a10ffbbd32fb08e437b68abde Mon Sep 17 00:00:00 2001 From: Loyal-Young <266632325+Loyal-Young@users.noreply.github.com> Date: Thu, 12 Nov 2026 23:21:49 +0800 Subject: [PATCH] docs: document UTL_FILE line I/O MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add the missing bilingual UTL_FILE usage and design pages. Show how to map a server directory, open a file, write and read a line, and remove the example data. Assisted-by: Codex:GPT-6 Percentage of AI-generated code: 100% Signed-off-by: 王泽浩 <266632325+Loyal-Young@users.noreply.github.com> --- .../utl_file_impl.adoc | 14 +++++++ .../oracle_compatibility/compat_utl_file.adoc | 42 +++++++++++++++++++ .../utl_file_impl.adoc | 14 +++++++ .../oracle_compatibility/compat_utl_file.adoc | 42 +++++++++++++++++++ 4 files changed, 112 insertions(+) create mode 100644 CN/modules/ROOT/pages/master/compatibility_features_design/utl_file_impl.adoc create mode 100644 CN/modules/ROOT/pages/master/oracle_compatibility/compat_utl_file.adoc create mode 100644 EN/modules/ROOT/pages/master/compatibility_features_design/utl_file_impl.adoc create mode 100644 EN/modules/ROOT/pages/master/oracle_compatibility/compat_utl_file.adoc diff --git a/CN/modules/ROOT/pages/master/compatibility_features_design/utl_file_impl.adoc b/CN/modules/ROOT/pages/master/compatibility_features_design/utl_file_impl.adoc new file mode 100644 index 00000000..3352f9f1 --- /dev/null +++ b/CN/modules/ROOT/pages/master/compatibility_features_design/utl_file_impl.adoc @@ -0,0 +1,14 @@ +:sectnums: +:sectnumlevels: 5 + += UTL_FILE 实现 + +== 查找目录 + +`UTL_FILE` 包通过 `sys.utl_file_directory` 解析目录别名。`contrib/ivorysql_ora/src/builtin_packages/utl_file/utl_file.c` 中的 C 实现打开解析出的服务器路径。文件操作受数据库服务进程的文件系统权限约束。 + +== 文件句柄与行 + +`FOPEN` 返回一个包记录,其 ID 对应当前后端的打开文件槽位。后续操作据此获取文件流和配置的行长度限制。`GET_LINE` 从流中读取一行,并用 `no_data_found` SQL 条件报告文件末尾。`FCLOSE` 释放槽位供后续打开文件时使用。 + +完整示例见 xref:master/oracle_compatibility/compat_utl_file.adoc[UTL_FILE 包]。 diff --git a/CN/modules/ROOT/pages/master/oracle_compatibility/compat_utl_file.adoc b/CN/modules/ROOT/pages/master/oracle_compatibility/compat_utl_file.adoc new file mode 100644 index 00000000..58e61f0d --- /dev/null +++ b/CN/modules/ROOT/pages/master/oracle_compatibility/compat_utl_file.adoc @@ -0,0 +1,42 @@ +:sectnums: +:sectnumlevels: 5 + += UTL_FILE 包 + +== 登记服务器目录 + +`UTL_FILE` 读写的是数据库服务器上的文件。为本示例准备一个数据库服务进程可写的空目录,并替换下方路径。请用能够管理 `sys.utl_file_directory` 的数据库管理员角色连接 Oracle 兼容模式。 + +目录记录将逻辑名称映射到文件系统路径。调用 `FOPEN` 时分别传入目录名和文件名。`w` 模式会创建新文件或截断已有文件,因此请为示例使用独立目录。 + +== 写入并读取一行 + +[source,sql] +---- +INSERT INTO sys.utl_file_directory(dirname, dir) +VALUES ('utl_file_demo', '/srv/ivorysql/utl-file-demo'); + +DECLARE + file_handle utl_file.file_type; + line_text text; +BEGIN + file_handle := utl_file.fopen('utl_file_demo', 'invoice-demo.txt', 'w', 100); + utl_file.put_line(file_handle, 'invoice=42'); + utl_file.fclose(file_handle); + + file_handle := utl_file.fopen('utl_file_demo', 'invoice-demo.txt', 'r', 100); + utl_file.get_line(file_handle, line_text); + utl_file.fclose(file_handle); + RAISE NOTICE '%', line_text; +END; +/ + +CALL utl_file.fremove('utl_file_demo', 'invoice-demo.txt'); +DELETE FROM sys.utl_file_directory WHERE dirname = 'utl_file_demo'; +---- + +代码块会显示 `NOTICE: invoice=42`。最后两条命令删除示例文件和目录映射。 + +`GET_LINE` 将下一行写入输出变量。读到文件末尾时会抛出 `no_data_found`,可在循环中捕获该条件以结束读取。用完每个文件句柄后请调用 `FCLOSE`。 + +实现细节见 xref:master/compatibility_features_design/utl_file_impl.adoc[UTL_FILE 实现]。 diff --git a/EN/modules/ROOT/pages/master/compatibility_features_design/utl_file_impl.adoc b/EN/modules/ROOT/pages/master/compatibility_features_design/utl_file_impl.adoc new file mode 100644 index 00000000..e3f3ff06 --- /dev/null +++ b/EN/modules/ROOT/pages/master/compatibility_features_design/utl_file_impl.adoc @@ -0,0 +1,14 @@ +:sectnums: +:sectnumlevels: 5 + += UTL_FILE Implementation + +== Directory lookup + +The `UTL_FILE` package resolves directory aliases through `sys.utl_file_directory`. The C implementation in `contrib/ivorysql_ora/src/builtin_packages/utl_file/utl_file.c` opens the resulting server-side path. The server process's filesystem permissions apply to the file operation. + +== File handles and lines + +`FOPEN` returns a package record whose ID identifies an open file slot in the backend. Subsequent operations use that slot to find the stream and its configured line limit. `GET_LINE` reads a line from the stream and uses the `no_data_found` SQL condition to signal end of file. `FCLOSE` releases the slot for later opens. + +For an end-to-end example, see xref:master/oracle_compatibility/compat_utl_file.adoc[UTL_FILE package]. diff --git a/EN/modules/ROOT/pages/master/oracle_compatibility/compat_utl_file.adoc b/EN/modules/ROOT/pages/master/oracle_compatibility/compat_utl_file.adoc new file mode 100644 index 00000000..7b229d5f --- /dev/null +++ b/EN/modules/ROOT/pages/master/oracle_compatibility/compat_utl_file.adoc @@ -0,0 +1,42 @@ +:sectnums: +:sectnumlevels: 5 + += UTL_FILE Package + +== Register a server directory + +`UTL_FILE` reads and writes files on the database server. For this example, use a fresh directory writable by the server process. Replace the path below with the actual directory. Run the example in Oracle compatibility mode as a database administrator who can manage entries in `sys.utl_file_directory`. + +An entry maps a directory name to a filesystem path. Pass that name and the filename separately to `FOPEN`. The mode `w` starts a new file or truncates an existing file, so use a dedicated directory for the example. + +== Write and read one line + +[source,sql] +---- +INSERT INTO sys.utl_file_directory(dirname, dir) +VALUES ('utl_file_demo', '/srv/ivorysql/utl-file-demo'); + +DECLARE + file_handle utl_file.file_type; + line_text text; +BEGIN + file_handle := utl_file.fopen('utl_file_demo', 'invoice-demo.txt', 'w', 100); + utl_file.put_line(file_handle, 'invoice=42'); + utl_file.fclose(file_handle); + + file_handle := utl_file.fopen('utl_file_demo', 'invoice-demo.txt', 'r', 100); + utl_file.get_line(file_handle, line_text); + utl_file.fclose(file_handle); + RAISE NOTICE '%', line_text; +END; +/ + +CALL utl_file.fremove('utl_file_demo', 'invoice-demo.txt'); +DELETE FROM sys.utl_file_directory WHERE dirname = 'utl_file_demo'; +---- + +The block prints `NOTICE: invoice=42`. The final commands remove the example file and its directory mapping. + +`GET_LINE` reads the next line into an output variable. At the end of a file it raises the `no_data_found` condition, which a loop can handle to stop reading. Use `FCLOSE` when finished with each handle. + +See xref:master/compatibility_features_design/utl_file_impl.adoc[UTL_FILE implementation].