Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
@@ -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 包]。
Original file line number Diff line number Diff line change
@@ -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 实现]。
Original file line number Diff line number Diff line change
@@ -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].
Original file line number Diff line number Diff line change
@@ -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].
Loading