UTL_FILE包可以用来读写操作系统上的文件，提供了在客户端操作服务器端文件的功能。它提供一套严格的使用标准操作系统文件I/O方式：OPEN、 PUT、 GET和 CLOSE操作；其中，GET方法用于读文件，PUT方法用于写文件。当用户读取或写入一个数据文件的时候，可以使用FOPEN返回的文件句柄，这个文件句柄将用于随后在文件上的所有操作，包含读、写、删除、重命名文件等。

本章介绍使用UTL_FILE读写系统文件的方法，从而可以利用UTL_FILE将表数据导出到文本文件，也可以将文本文件写入表中。

UTL_FILE数据类型

UTL_FILE定义了一种FILE_TYPE记录类型。FILE_TYPE类型是UTL_FILE专有类型。用户不能引用和改变该记录的内容。FILE_TYPE记录类型定义如下：

参数详解：

ID：需要处理的外部文件句柄。

DATATYPE：文件的类型。1表示CHAR 、2表示NCHAR、3表示BINARY。

BYTE_MODE：文件打开后的类型。TRUE表示二进制模式；FALSE表示文本模式。

UTL_FILE相关方法

FOPEN打开文件

FOPEN用于打开指定文件，其返回一个FILE_TYPE类型的活动文件句柄。用户指定文件每行最大的字符数，并且同时可以打开文件最多50个。语法如下：

参数详解

LOCATION：源文件路径。

FILENAME：文件名称，包括文件类型，但不包含文件路径。如果文件名称中包含路径，则 FOPEN忽略此处的路径。在UNIX系统中，文件名不能包含转义符：“/”。

OPEN_MODE：文件的打开模式。包含'r', 'w', 'a' 'rb', 'wb', 'ab'六种：

① 'r'：读文件(文本)，一定要保证有该文件，不然会报INVALID_PATH异常；

② 'w'：写文件(文本)，没有该文件的话会自动添加；有的话会覆盖；

③ 'a'：追加文件(文本)，如果文件不存在，则会以write模式创建此文件；

④ 带有'b'后缀的为使用byte(字节)模式，BLOB打开时一定要用带有'b'后缀的模式。

MAX_LINESIZE：文件每行最大的字符数，包括换行符。最小为1，最大为32767。

说明：读取或者写入文件都需要先调用FOPEN，返回该文件活动句柄，以便做后续操作。

PUT/PUT_LINE/PUT_RAW/PUTF写入文件

PUT用于将缓冲区内容写入到文件中（不带换行符）。当使用PUT过程的时候，文件必须以写方式打开，在写入缓冲区之后，如果要结束行，可以使用NEW_LINE过程。语法如下：

参数详解 

FILE：由FOPEN返回的活动文件句柄。

BUFFER：包含要写入文件的数据缓存。BUFFER参数的最大长度是32767，如果未指定，FOPEN默认的行最大值为1024。连续调用PUT的总和在没有缓冲区刷页的情况下不能超过32767。PUT_LINE用于将文本缓冲区内容写入到文件中（每写一次，末尾都加一个换行符）。语法如下：

参数详解

FILE，BUFFER：略。

AUTOFLUSH：数据写完后，缓冲区自动冲刷。

说明：PUT_LINE用于写入文本数据。如果文件以BYTE模式打开，则产生INVALID_OPERATION异常。

PUT_RAW用于接收输入的原始数据（二进制数据）并将其写入缓存。语法如下：

PUTF写入格式化的内容到文件中。类似C中的PRINTF()。语法如下：

参数详解

FORMAT包含格式化字符[\n，%s]的内容。\n：代表一个换行符。%s：用ARG1~5的值去代替。

GET_LINE/GET_RAW读取文件

GET_LINE用于从已经打开的文件中读取行内容，行内容会被读取到输出缓冲区。语法如下：

参数详解

FILE：由FOPEN返回的活动文件句柄。

BUFFER：接收数据文件中行读的数据缓冲区。

LEN：从文件中读取的字节数。默认情况为NULL，NULL表示读取的字节数为MAX_LINESIZE。

说明：

如果该行不匹配缓冲区，则发生READ_ERROR异常。如果到文件结束了仍没有文本读取，发生NO_DATA_FOUND异常。如果文件以BYTE模式打开，则产生INVALID_OPERATION异常。

缓冲区最大大小为32767字节，除非FOPEN指定了更小的值。如果未指定，默认值为1024。

GET_RAW从文件中读取原始字符串值（二进制数据），并通过读取的字节数调整文件指针的头部。GET_RAW函数忽略掉行结束符，并返回通过GET_RAW的LEN参数请求的实际字节数。语法如下：

FGETATTR获取文件属性

FGETATTR读取并返回磁盘文件的属性。语法如下： 

参数详解

LOCATION：源文件路径。

FILENAME：被检查的文件。

FEXISTS：文件是否存在，存在为TRUE，不存在为FALSE。

FILE_LENGTH：文件的长度（字节），若文件不存在，则长度为NULL。

BLOCKSIZE：文件系统中数据块的大小（字节），若文件不存在，则长度为NULL。

FGETPOS获取数据位置

FGETPOS用于获取指定文件中当前相对位置偏移量（字节）。以字节的方式返回一个打开文件相对位置偏移量，如果文件未打开则发生异常。如果当前位置在文件的最开始，则返回0。语法如下：

FFLUSH刷新缓存

FFLUSH用于将数据强制性写入到文件中，正常情况下，当给文件写入数据的时候，数据会被暂时的放到缓存中。FFLUSH用于强制将数据写入到文件中。数据必须以换行符结束。当有必要去read一个任然处于打开状态的文件时，FFLUSH就起作用了，例如在调试程序中，可以将调试的消息及时冲到文件中，以便于我们马上就能read这些内容。语法如下：

FCLOSE关闭文件

FCLOSE用于关闭一个已经打开的文件。语法如下：

说明：读写文件完成之后都需要调用FCLOSE来关闭文件。

UTL_FILE使用方法

UTL_FILE包使用有如下限制：

1. 如果是非WINDOWS环境，且运行达梦服务器的进程有效用户为root，则禁止文件操作；

2. 执行操作的数据库用户必须有DBA权限；

3 只能创建、修改在达梦系统目录（含子目录）下的文件。

下面用两个案例介绍UTL_FILE写入和读取文本文件的方法。

写入文件的顺序是：FOPEN（打开文件）->PUT/PUT_LINE/PUT_RAW/PUTF（写入数据）->FFLUSH（刷新缓存，可选）->FCLOSE（关闭文件）；

读取文件的顺序是：FOPEN（打开文件）->GET_LINE/GET_RAW（读取数据）->FCLOSE（关闭文件）。

案例一：将表数据写入文件

本章以DMHR用户测试，使用UTL_FILE将EMPLOYEE表数据导出为EXCEL或CSV格式文件（这里仅仅导出employee_id, employee_name, identity_card, email四列），导出路径为DM安装数据库实例目录下test文件夹（test文件夹需提前手工创建）。在使用UTL_FILE之前，需要先将dba角色权限赋给DMHR用户，否则调用UTL_FILE.FOPEN会报错：“UTL_FILE.FOPEN无访问权限”。

使用SYSDBA用户执行如下语句（赋予DMHR用户dba角色权限）：

使用DMHR用户创建存储过程p_readfiledata，实现上述导出EMPLOYEE表数据的功能（文件名和字段分隔符作为入参指定，默认为excel文件，制表符分隔）。语句参考如下：

执行如下命令调用存储过程：

执行完成后，在d:\dmdbms\data\dameng\test目录下生成文件employee.xls，查看文件内容如下：

（所涉及个人信息纯属虚构）

重新调用存储过程，指定参数文件名employee.csv，字段分隔符“，”，导出csv文件格式，命令参考如下：

执行完成后，在相同目录下生成文件employee.csv，查看文件内容如下：

（所涉及个人信息纯属虚构）

案例二：读取数据文件

①使用DMHR用户创建存储过程p_readfiledata，实现使用UTL_FILE读取案例一中导出的文本文件employee.csv的功能，语句参考如下：

因为存储过程中使用了dbms_output.put_line输出功能，我们在DISQL命令行下执行该过程之前，需执行set serveroutput on打开输出功能。

使用DISQL工具登录DM数据库（以DMHR用户登录），执行如下命令：

执行完成后，DISQL窗口打印信息如下：

（所涉及个人信息纯属虚构）

②使用DMHR用户创建存储过程p_readrawdata，实现使用UTL_FILE读取案例一中导出的数据文件employee.csv原始字节内容的功能，语句参考如下：

在DM管理工具界面执行此存储过程，查看结果集数据显示如下。可看出GET_RAW一次性读取了数据文件所有原始内容（二进制数据），显示为0x开头十六进制字符串，单击“另存为”保存为txt文本文件，查看txt文件内容与employee.csv文件一致。