接口介绍

高级功能包UTL_FILE支持的所有接口请参见表1。

• UTL_FILE.FOPEN

  该函数用来打开一个文件，可以指定最大行的大小，最多可以同时打开50个文件。并且该函数返回FILE_TYPE类型的一个句柄。

  UTL_FILE.FOPEN函数原型为：

  1 2 3 4 5 6

  UTL_FILE.FOPEN ( location IN VARCHAR2, filename IN VARCHAR2, open_mode IN VARCHAR2, max_linesize IN INTEGER DEFAULT 1024) RETURN FILE_TYPE;

  表2 UTL_FILE.FOPEN接口参数说明

  参数	描述
  location	文件的目录位置，这个字符串是一个目录对象名。 说明： 文件目录的位置，需要添加到系统表PG_DIRECTORY中，如果传入的路径和PG_DIRECTORY中的路径不匹配，会报路径不存在的错误， 下面的涉及location作为参数的函数也是同样的情况。
  filename	文件名，包含扩展（文件类型），不包括路径名。如果文件名中包含路径，在FOPEN中会被忽略，在Unix系统中，文件名不能以/.结尾。
  open_mode	指定文件的打开模式，包含r：read text，w: write text和a: append text。
  max_linesize	每行最大字符数，包含换行符（最小值是1，最大值是32767）。如果没有指定，Oracle会指定一个默认值1024。

• UTL_FILE.IS_OPEN

  该函数用于检测一个文件句柄来查看文件是否已经打开，返回一个布尔值，异常情况是INVALID_FILEHANDLE。

  UTL_FILE.IS_OPEN函数原型为：

  1 2 3

  UTL_FILE.IS_OPEN ( file IN FILE_TYPE) RETURN BOOLEAN;

  表3 UTL_FILE.IS_OPEN接口参数说明

  参数	描述
  file IN FILE_TYPE	传入一个要检测的文件句柄。

• UTL_FILE.GET_LINE

  该存储过程从一个打开的文件句柄中读取文本，并把读取的结果存放到BUFFER中。读取的时候会读取到行尾，不包含行终结符或者读取到文件末尾，或者达到了len参数指定的大小，读取的长度不能超过FOPEN的时候指定的max_linesize。

  UTL_FILE.GET_LINE函数原型为：

  1 2 3 4

  UTL_FILE.GET_LINE ( file IN FILE_TYPE, buffer OUT VARCHAR2, len IN INTEGER DEFAULT NULL)

  表4 UTL_FILE.GET_LINE接口参数说明

  参数	描述
  file	通过调用FOPEN打开的文件句柄，文件必须以读的模式打开，否则会抛出INVALID_OPERATION的异常。
  buffer	用于接收数据的BUFFER。
  len	从文件中读取的字节数，默认是NULL。如果是默认NULL，会使用max_linesize来指定大小。

• UTL_FILE.PUT

  该存储过程用于向文件中写入BUFFER中的数据，要写入的文件必须以写模式打开，这个操作不会写入行终结符。

  UTL_FILE.PUT函数原型为：

  1 2 3

  UTL_FILE.PUT ( file IN FILE_TYPE, buffer IN VARCHAR2);

  表5 UTL_FILE.PUT接口参数说明

  参数	描述
  file	该存储过程用于向文件中写入BUFFER中的数据，要写入的文件必须以写模式打开，这个操作不会写入行终结符。
  buffer	要写入文件的文本数据，BUFFER的最大值是32767个字节。如果在open的时候没有指定值，默认是1024个字节，没有刷新到文件之前，一系列的PUT操作的BUFFER总和不能超过32767个字节。

• UTL_FILE.NEW_LINE

  该存储过程用于向一个打开的文件中写入一个或者多个行终结符。这个存储过程是从PUT函数中拆分出来的，因为行终结符和平台相关。

  UTL_FILE_NEW_LINE函数原型为：

  1 2 3

  UTL_FILE.NEW_LINE ( file IN FILE_TYPE, lines IN INTEGER := 1);

  表6 UTF_FILE.NEW_LINE接口参数说明

  参数	描述
  file	一个打开的文件句柄。
  lines	写入到文件中的终结符的数量。

• UTL_FILE.PUT_LINE

  该存储过程将BUFFER中的字符串写入到一个打开的文件中，文件必须以写模式打开。

  UTL_FILE.PUT_LINE函数原型为：

  1 2 3 4

  UTL_FILE.PUT_LINE ( file IN FILE_TYPE, buffer IN VARCHAR2, autoflush IN BOOLEAN DEFAULT FALSE);

  表7 UTL_FILE.PUT_LINE接口参数说明

  参数	描述
  file	一个打开的文件句柄。
  buffer	要写入文件的文本数据，BUFFER的最大值是32767个字节。如果在open的时候没有指定值，默认是1024个字节，没有刷新到文件之前，一系列的PUT操作的BUFFER总和不能超过32767个字节。
  autoflush	在write后是否要刷到磁盘。

• UTL_FILE.PUTF

  该存储过程是一个格式化的PUT存储过程，行为类似printf()。

  UTL_FILE.PUTF函数原型为：

  1 2 3 4 5 6

  UTL_FILE.PUTF ( file IN FILE_TYPE, format IN VARCHAR2, [arg1 IN VARCHAR2 DEFAULT NULL, . . . arg5 IN VARCHAR2 DEFAULT NULL]);

  表8 UTL_FILE.PUTF接口参数说明

  参数	描述
  file	一个打开的文件句柄。
  format	一个要进行格式化的字符串包含，文本和格式符\n和%s。
  [arg1. . .arg5]	从1到5个可选的参数串，参数和格式化字符的位置是一一对应的，如果存在格式化字符而没有提供参数，会使用空串来替代%s。

• UTL_FILE.FFLUSH

  一个文件句柄中的数据要写入到物理文件中，缓冲区中的数据必须要有一个行终结符。当文件必须在打开时读取，刷新非常有用。例如，调试信息可以刷新到文件中，以便立即读取。

  UTL_FILE.FFLUSH函数原型为：

  1 2	UTL_FILE.FFLUSH ( file IN FILE_TYPE);

  表9 UTL_FILE.FFLUSH接口参数说明

  参数	描述
  file	一个打开的文件句柄。

• UTL_FILE.FCLOSE

  该存储过程用于关闭一个打开的文件句柄，当调用这个存储过程的时候，如果还有等待写入的缓存的数据，可能会收到异常信息。

  UTL_FILE.FCLOSE函数原型为：

  1 2	UTL_FILE.FCLOSE ( file IN OUT FILE_TYPE);

  表10 UTL_FILE.FCLOSE接口参数说明

  参数	描述
  location	一个打开的文件句柄。

• UTL_FILE.FCLOSE_ALL

  该存储过程关闭一个会话中打开的所有的文件句柄，可用于紧急的清理操作。

  UTL_FILE.FCLOSE_ALL函数原型为：

  1	UTL_FILE.FCLOSE_ALL;

  表11 UTL_FILE.FCLOSE_ALL接口参数说明

  参数	描述
  无	无

• UTL_FILE.FREMOVE

  该存储过程删除一个磁盘文件，操作的时候对目录和文件要有充分的权限。

  UTL_FILE.FREMOVE函数原型为：

  1 2 3

  UTL_FILE.FREMOVE ( location IN VARCHAR2, filename IN VARCHAR2);

  表12 UTL_FILE.FREMOVE接口参数说明

  参数	描述
  location	文件所在的目录位置。
  filename	要删除的文件。

• UTL_FILE.FRENAME

  对磁盘上的文件进行重命名，类似Unix的mv。

  UTL_FILE.FRENAME函数原型为：

  1 2 3 4 5 6

  UTL_FILE.FRENAME ( src_location IN VARCHAR2, src_filename IN VARCHAR2, dest_location IN VARCHAR2, dest_filename IN VARCHAR2, overwrite IN BOOLEAN DEFAULT FALSE);

  表13 UTL_FILE.FRENAME接口参数说明

  参数	描述
  src_location	原文件的目录位置（大小写敏感）。
  src_filename	要进行命名的原文件。
  dest_location	目的目录（大小写敏感）。
  dest_filename	新的文件名。
  overwrite	默认是false，如果目的目录下存在一个同名的文件，不会进行重写。

• UTL_FILE.FCOPY

  该存储过程拷贝一个连续的区域内容到一个新创建的文件中，如果忽略了start_line和end_line会拷贝整个文件。

  UTL_FILE.FCOPY函数原型为：

  1 2 3 4 5 6 7

  UTL_FILE.FCOPY ( src_location IN VARCHAR2, src_filename IN VARCHAR2, dest_location IN VARCHAR2, dest_filename IN VARCHAR2, start_line IN INTEGER DEFAULT 1, end_line IN INTEGER DEFAULT NULL);

  表14 UTL_FILE.FCOPY接口参数说明

  参数	描述
  src_location	原文件所在的目录。
  src_filename	要拷贝的原文件。
  dest_location	目的文件所在的目录。
  dest_filename	要写入的目的文件。
  start_line	拷贝开始的行号，默认是1。
  end_line	拷贝结束的行号，默认是NULL，指定到文件尾。

• UTL_FILE.FGETATTR

  该存储过程用于读取并返回磁盘文件的属性。

  UTL_FILE.FGETATTR函数原型为：

  1 2 3 4 5 6

  UTL_FILE.FGETATTR( location IN VARCHAR2, filename IN VARCHAR2, fexists OUT BOOLEAN, file_length OUT NUMBER, block_size OUT INTEGER);

  表15 UTL_FILE.FGETATTR接口参数说明

  参数	描述
  location	文件所在的目录。
  filename	要检测的文件名。
  fexists	返回文件是否存在的值。
  file_length	文件的字节长度，如果文件不存在返回NULL。
  block_size	文件系统的块大小（单位字节），如果文件不存在返回NULL。

• UTL_FILE.FSEEK

  该存储过程会根据用户指定的字节数向前或者向后调整文件指针的位置。

  UTL_FILE.FSEEK函数原型为：

  1 2 3 4

  UTL_FILE.FSEEK ( file IN OUT UTL_FILE.FILE_TYPE, absolute_offset IN INTEGER DEFAULT NULL, relative_offset IN INTEGER DEFAULT NULL);

  表16 UTL_FILE.FSEEK接口参数说明

  参数	描述
  file	一个打开的文件句柄。
  absolute_offset	文件偏移的绝对位置，这个默认值为NULL。
  relative_offset	文件偏移的相对位置。如果这个值是正数，向前偏移；如果是负数，向后偏移；默认值为NULL。如果和absolute_offset参数同时指定，以absolute_offset参数为准。

• UTL_FILE.FGETPOS

  函数返回文件的偏移量，单位字节。

  UTL_FILE.FGETPOS函数原型为：

  1 2 3

  UTL_FILE.FGETPOS ( file IN FILE_TYPE) RETURN BIGINT;

  表17 UTL_FILE.FGETPOS接口参数说明

  参数	描述
  file	一个打开的文件句柄。

示例

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52

--系统管理员向PG_DIRECTORY系统表中加入目录/temp/：
CREATE OR REPLACE DIRECTORY dir AS '/tmp/';
--打开一个文件并向文件中写入数据                                                                                                                   
DECLARE
  f utl_file.file_type;
  dir text := 'dir';
BEGIN
  f := utl_file.fopen(dir, 'sample.txt', 'w');
  PERFORM utl_file.put_line(f, 'ABC');
  PERFORM utl_file.put_line(f, '123'::numeric);
  PERFORM utl_file.put_line(f, '-----');
  PERFORM utl_file.new_line(f);
  PERFORM utl_file.put_line(f, '*******');
  PERFORM utl_file.new_line(f, 0);
  PERFORM utl_file.put_line(f, '++++++++');
  PERFORM utl_file.new_line(f, 2);
  PERFORM utl_file.put_line(f, '#######');
  PERFORM utl_file.put(f, 'A');
  PERFORM utl_file.put(f, 'B');
  PERFORM utl_file.new_line(f);
  PERFORM utl_file.putf(f, '[1 -> %s, 2 -> %s, 3 -> %s, 4 -> %s, 5 -> %s]', 'gaussdb', 'utl', 'file', 'get', 'line');
  PERFORM utl_file.new_line(f);
  PERFORM utl_file.put_line(f, '1234567890');
  f := utl_file.fclose(f);
END;
/
--在上面写入的文件中读取数据。
DECLARE
  f utl_file.file_type;
  dir text := 'dir';
BEGIN
  f := utl_file.fopen(dir, 'sample.txt', 'r');
  FOR i IN 1..11 LOOP
       RAISE INFO '[%] : %', i, utl_file.get_line(f);
  END LOOP;
END;
/
-- 对文件句柄执行位置偏移，并获取文件的当前位置。                                                                                                 
DECLARE
      l_file   utl_file.file_type;
      l_buffer VARCHAR2(32767);
      dir text := 'dir';
      abs_offset number := 100;
      rel_offset number := NULL;
BEGIN
      l_file := utl_file.fopen(location  => dir,  filename  => 'sample.txt',open_mode => 'R');
      dbms_output.put_line('before fseek: current position is ' || utl_file.fgetpos(file => l_file)); -- before fseek: current position is 0
      utl_file.fseek(file => l_file, absolute_offset=>abs_offset, relative_offset=>rel_offset);
      dbms_output.put_line('fseek: current position is ' || utl_file.fgetpos(file => l_file)); -- fseek: current position is 100
      utl_file.fclose(file=>l_file);
END;
/