二十一、utl_file（用于读写OS文件）

1、概述

作用:用于读写OS文件.使用该包访问OS文件时,必须要为OS目录建立相应的DIRECTORY对象..当用户要访问特定目录下的文件时,必须要具有读写DIRECTORY对象的权限.在使用UTL_FILE包之前,应首先建立DIRECTORY对象.

2、包的组成

1）、file_type
作用：该类型是utl_file包中所定义的记录类型，其成员是私有的，不能被直接引用。
该类型的定义如下：
type file_type is record(is binary_integer,datatype binary_integer);

2）、fopen
作用：用于打开OS文件。注意，使用该函数最多可以同时打开50个文件
语法：file_type.fopen(
location in varchar2,filename in varchar2,
open_mode in varchar2,max_linesize in binary_integer) return file_type;
说明：当成功执行后会返回文件句柄，访问该文件可以直接使用文件句柄。
如果执行失败会触发异常或显示错误。注意当指定文件位置时必须要使用directory对象，且其名称必须大写。

3）、fopen_nchar
作用：用于以unicode方式打开文件。当使用该函数打开文件后，读写文件会使用unicode取代数据库字符集。
语法：utl_file.fopen_nchar(
location in varchar2,
filename in varchar2,
open_mode in varchar2
max_linesize in binary_integer) return file_type;

4）、is_open
作用：用于确定文件是否已经打开
语法：utl_file.is_open(file in file_type) return boolean;
其中file指定文件句柄，如果文件已经被打开返回true，否则返回false。

5）、fclose
作用：用于关闭已经打开的文件
语法：utl_file.fclose(file in out file_type);

6）、fclose_all
作用：用于关闭当前会话打开的所有文件
语法：utl_file.fclose_all;

7）、get_line
作用：用于从已打开文件中读取行内容，行内容会被读取到输出缓冲区
语法：utl_file.get_line(file in file_type,buffer out varchar2,
linesize in number,len in pls_integer default null);
其中buffer用于存储读取信息，linesize指定要读取的最大字节输，len指定实际读取长度。

8）、get_line_nchar
作用：用于以unicode方式读取已打开文件的行内容，并且将行内容读取到输出缓冲区。
语法：utl_file.get_line_nchar(file in file_type,buffer out varchar2,
len in pls_integer default null);

9）、get_raw
作用：用于从文件中读取raw字符串，并调节文件指针到读取位置。
语法：utl_file.get_raw(fid in utl_file.file_type,r out nocopy raw,
len in pls_integer default null);

10）、put
作用：用于将缓冲区内容写入到文件中，当使用put过程时文件必须要以写方式打开。
在写入缓冲区内容后如果要结束行，可以用new_line过程。
语法：utl_file.put(file in file_type,buffer in varchar2);

11）、put_nchar
作用：用于将缓冲区内容以unicode方式写入到文件。
语法：utl_file.put_nchar(file in file_type,buffer in varchar2);

12）、put_raw
作用：用于将raw缓冲区中的数据写入到OS文件。
语法：utl_file.put_raw(fid in utl_file.file_type,r in raw,
autoflush in boolean default false);
其中fid指定文件句柄，r指定存放raw数据的缓冲区，autoflush指定是否要自动刷新缓冲区数据。

13）、new_line
作用：用于为文件增加行终止符。
语法：utl_file.new_line(file in file_type,lines in natural:=1);
其中lines指定要增加的行终止符个数。

14）、put_line
作用：用于将文本缓冲区内容写入到文件中。当使用该过程为文本追加内容时会自动在内容的尾部追加终止符。
语法：utl_file.put_line(file in file_type,buffer in varchar2,
autoflush in boolean default false);

15）、put_line_nchar
作用：用于将文本缓冲区内容以unicode方式写入文件。自动在尾部追加终止符。
语法：utl_file.put_line_nchar(file in file_type,buffer in varchar2);

16）、putf
作用：用于以特定格式将文本内容写入到OS文件，其中格式符%s表示字符串，格式符\n表示行终止符。
语法：utl_file.putf(file in file_type,format in varchar2
[,arg1 in varchar2 default null,...arg5 in varchar2 default null]);
其中format指定格式符（最多5个%s），arg1...arg5指定对应格式符的字符串。

17）、putf_nchar
作用：用于以特定格式将文本内容以unicode的方式写入到OS文件，其中格式符%s表示字符串，格式符\n表示行终止符。
语法：utl_file.putf_nchar(file in file_type,format in varchar2
[,arg1 in varchar2 default null,...arg5 in varchar2 default null]);
其中format指定格式符（最多5个%s），arg1...arg5指定对应格式符的字符串。

18）、fflush
作用：用于将数据强制性写入到OS文件。正常情况下当给文件写入数据时，
数据会被暂时存放在缓冲中，过程fflush用于强制将数据写入到OS文件中。
语法：utl_file.fflush(file in file_type);

19）、fseek
作用：用于移动文件指针到特定位置。既可以指定文件指针的绝对位置，也可以指定文件指针的相对位置。
语法：utl_file.fseek(
fid in utl_file.file_type,absolute_offset in pl_integer default null,
relative_offset in pls_integer default null);
其中absolute_offset指定文件指针的绝对位置(单位：字节)，
relative_offset指定文件指针的相对位置（单位：字节）。

20）、fremove
作用：用于删除磁盘文件
语法：utl_file.fremove(location in varchar2,filename in varchar2);
其中location指定directory对象（必须大写），filename指定要删除的OS文件名。

21）、fcopy
作用：用于将源文件的全部或部分内容复制到目标文件中。如果不设置起始行和结束行则复制文件所有内容。
语法：utl_file.fcopy(location ni varcahr2,
filename in varchar2,
dest_dir in varchar2,
dest_file in varchar2,
start_line in pls_integer default 1,
end_line in pls_integer default null);
其中location指定源文件所在目录对应的directory对象，filename指定源文件名，
dest_dir指定目标文件所在目录对应的directory对象，dest_file指定目标文件的名字，
start_line指定起始行号，end_line指定结束行号。
例子：exec utl_file.fcopy('USER_DIR','a.txr','USER_DIR','c.txt');

22）、fgetpos
作用：返回文件指针所在的偏移位置。
语法：utl_file.fgetpos(fileid in file_type) return pls_integer;

23）、fgetattr
作用：用于读取磁盘文件，并返回文件属性
语法：utl_file.fgetattr(location in varchar2,filename in varchar2,
exists out boolean,file_length out number,blocksize out number)
其中location指定OS目录所对应的directory对象，filename指定OS文件名，
exists确定文件是否存在，file_length取得文件长度，blocksize取得OS块的尺寸。

24）、frename
作用：用于修改已存在的OS文件名，其作用与unix的mv命令完全相同。
在修改文件名时，通过指定overwrite参数，可以覆盖已存在的文件。
语法：utl_file.frename(location in varchar2,filename in varchar2,dest_dir in varchar2,
dest_file in varchar2,overwrite in boolean default false);
其中overwrite指定是否要覆盖已存在文件(false:不能覆盖，true:覆盖)。
例子：exec utl_file.frename('USER_DIR','d.txt','USER_DIR','c.txt');

3、综合例子

declare
handle utl_file.file_type;
buffer varchar2(100);
buffer1 raw(100);
fileexist boolean;
filelen int;
os_block int;
begin
--is_open
if not utl_file.is_open(handle) then
--fopen
bandle:=utl_file.fopen('user_dir','readme.txt','r',1000);
end if;
dbms_output.put_line('打开文件成功');
--get_line
utl_file.get_line(handle,buffer,100);
dbms_output.put_line(buffer);
utl_file.fclose(handle);
--get_line_nchar
handle:=utl.file.fopen_nchar('USER_DIR','a.txt'.'r',1000);
utl_file.get_line_nchar(bandle.buffer);
dbms_output.put_line(buffer);
utl_file.fclose(handle);
--get_raw
handle:=utl_file.fopen('USER_DIR','a.txt'.'r',1000);
utl_file.get_raw(handle,buffer1,100);
dbms_output.put_line(buffer1);
utl_file.fclose(handle);
--put
handle:=utl_file.fopen('USER_DIR','b.txt'.'w',1000);
buffer:='中华';
utl_file.put(handle,buffer);
utl_file.new_line(handle);
buffer:='中国';
utl_file.put_line(handle,buffer);
utl_file.fclose(handle);
--put_nchar
handle:=utl_file.fopen('USER_DIR','b.txt'.'w',1000);
buffer:='中华';
utl_file.put(handle,buffer);
utl_file.new_line(handle);
buffer:='中国';
utl_file.put_line_nchar(handle,buffer);
utl_file.fclose(handle);
--put_raw
handle:=utl_file.fopen('USER_DIR','b.txt'.'w',1000);
buffer:='01f3d5a4c7d8';
utl_file.put_raw(handle,buffer);
utl_file.new_line(handle);
utl_file.fclose(handle);
--putf
handle:=utl_file.fopen('USER_DIR','b.txt'.'w',1000);
utl_file.putf(handle,'%s\n%s\n%s\n','历史','文明','万岁');
utl_file.fclose(handle);
--fseek
bandle:=utl_file.fopen('USER_DIR','a.txt','r');
dbms_output.put_line('文件指针起始位置:'||utl_file.fgetpos(handle));
utl_file.fseek(handle,20);
dbms_output.put_line('文件指针起当前位置:'||utl_file.fgetpos(handle));
utl_file.fclose(handle);
--fgetattr
utl_file.fgetatttr('USER_DIR','readme.txt',fileexist,filelen,os_block);
if fileexist then
dbms_output.put_line('文件尺寸：'||filelen);
dbms_output.put_line('OS块尺寸：'||os_block);
end if;
end;