更新时间:2024-11-01 GMT+08:00
分享

DBE_FILE

DBE_FILE包为存储过程提供了读、写操作系统文本文件的能力。

接口介绍

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

表1 DBE_FILE

接口名称

描述

DBE_FILE.OPEN

根据指定的目录和文件名打开一个文件。

DBE_FILE.IS_CLOSE

检测一个文件句柄是否关闭。

DBE_FILE.IS_OPEN

检测一个文件句柄是否打开。

DBE_FILE.READ_LINE

从一个打开的文件句柄中读取一行指定长度的数据。

DBE_FILE.WRITE

将数据写入到一个打开的文件的缓冲区中。

DBE_FILE.NEW_LINE

将一个或者多个行终结符写入到一个打开的文件的缓冲区中。

DBE_FILE.WRITE_LINE

将数据写入到一个打开的文件的缓冲区中,并自动追加一个行终结符。

DBE_FILE.FORMAT_WRITE

将数据按指定格式写入到一个打开的文件的缓冲区中。

DBE_FILE.GET_RAW

从一个打开的文件中读取指定字节数的RAW类型数据。

DBE_FILE.PUT_RAW

将RAW类型数据写入到一个打开的文件的缓冲区中。

DBE_FILE.FLUSH

将缓存区中的数据写入到物理文件中。

DBE_FILE.CLOSE

关闭一个打开的文件句柄。

DBE_FILE.CLOSE_ALL

关闭一个会话中打开的所有的文件句柄。

DBE_FILE.REMOVE

根据指定的目录和文件名删除一个磁盘文件,操作的时候需要有充分的权限。

DBE_FILE.RENAME

重命名一个磁盘文件,类似Unix的mv指令。

DBE_FILE.COPY

复制一个连续区域的内容到一个新创建的文件中,如果忽略了start_line和end_line会复制整个文件。

DBE_FILE.GET_ATTR

读取并返回一个磁盘文件的属性。

DBE_FILE.SEEK

根据用户指定的字节数向前或者向后调整文件指针的位置。

DBE_FILE.GET_POS

以字节为单位返回文件当前的偏移量。

  • DBE_FILE.OPEN

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

    DBE_FILE.OPEN函数原型为:

    1
    2
    3
    4
    5
    6
    DBE_FILE.OPEN (
    dir             IN    VARCHAR2,
    file_name       IN    VARCHAR2,
    open_mode       IN    VARCHAR2,
    max_line_size   IN    INTEGER DEFAULT 1024)
    RETURN INTEGER;
    
    表2 DBE_FILE.OPEN接口参数说明

    参数

    类型

    入参/出参

    是否可以为空

    描述

    dir

    VARCHAR2

    IN

    文件的目录位置,这个字符串是一个目录对象名。

    说明:
    • 文件目录的位置,需要添加到系统表PG_DIRECTORY中,如果传入的路径和PG_DIRECTORY中的路径不匹配,会报路径不存在的错误,下面的涉及location作为参数的函数也是同样的情况。
    • 在打开guc参数safe_data_path时,用户只能通过高级包读写safe_data_path指定文件路径下的文件。

    file_name

    VARCHAR2

    IN

    文件名,包含扩展(文件类型),不包括路径名。如果文件名中包含路径,在OPEN中会被忽略,在UNIX系统中,文件名不能以/.结尾。

    open_mode

    VARCHAR2

    IN

    指定文件的打开模式,包含r:read text,w: write text和a: append text。

    说明:

    对于写操作,会检测写入文件类型,如果为elf类型文件,会报错退出。

    max_line_size

    INTEGER

    IN

    每行最大字符数,包含换行符(最小值是1,最大值是32767)。如果没有指定,会指定一个默认值1024。

  • DBE_FILE.IS_OPEN

    函数DBE_FILE.IS_OPEN用于检测一个文件是否已经打开,返回一个布尔值,异常情况是INVALID_FILEHANDLE。

    DBE_FILE.IS_OPEN函数原型为:

    1
    2
    3
    DBE_FILE.IS_OPEN(
        file IN INTEGER)
    RETURN BOOLEAN;
    
    表3 DBE_FILE.IS_OPEN接口参数说明

    参数

    类型

    入参/出参

    是否可以为空

    描述

    file

    INTEGER

    IN

    待检测的文件句柄,为空时DBE_FILE.IS_OPEN接口返回FALSE。

  • DBE_FILE.IS_CLOSE

    函数DBE_FILE.IS_CLOSE用于检测一个文件句柄是否已经关闭,返回布尔值,异常情况是INVALID_FILEHANDLE。

    DBE_FILE.IS_CLOSE函数原型为:

    1
    2
    3
    DBE_FILE.IS_CLOSE (
    file      IN     INTEGER)
    RETURN BOOLEAN;
    
    表4 DBE_FILE.IS_CLOSE接口参数说明

    参数

    类型

    入参/出参

    是否可以为空

    描述

    file

    INTEGER

    IN

    传入一个要检测的文件句柄。

  • DBE_FILE.READ_LINE

    存储过程DBE_FILE.READ_LINE从一个打开的文件读取数据,并把读取的结果存放到BUFFER中。读取的时候会读取到行尾,但不包含行终结符,或者读取到文件末尾,或者读取到len参数指定的大小。读取的长度不能超过OPEN的时候指定的max_line_size。

    DBE_FILE.READ_LINE函数原型为:

    1
    2
    3
    4
    DBE_FILE.READ_LINE (
    file      IN   INTEGER,
    buffer    OUT  VARCHAR2,
    len       IN   INTEGER DEFAULT NULL)
    
    表5 DBE_FILE.READ_LINE接口参数说明

    参数

    类型

    入参/出参

    是否可以为空

    描述

    file

    INTEGER

    IN

    通过调用OPEN打开的文件句柄,文件必须以读的模式打开,否则会抛出INVALID_OPERATION的异常。

    buffer

    VARCHAR2

    OUT

    用于接收数据的BUFFER。

    len

    INTEGE

    IN

    从文件中读取的字节数,默认是NULL。如果是默认NULL,会使用max_line_size来指定大小。

  • DBE_FILE.WRITE

    函数DBE_FILE.WRITE用于向文件对应的缓冲区中写入BUFFER中的数据,文件必须以写模式打开,这个操作不会写入行终结符。

    DBE_FILE.WRITE函数原型为:

    1
    2
    3
    4
    DBE_FILE.WRITE (
    file     IN     INTEGER,
    buffer   IN     TEXT)
    RETURN BOOLEAN;
    
    表6 DBE_FILE.WRITE接口参数说明

    参数

    类型

    入参/出参

    是否可以为空

    描述

    file

    INTEGER

    IN

    通过OPEN打开的文件句柄,要写入的文件必须以写模式打开,这个操作不会写入行终结符。

    buffer

    TEXT

    IN

    要写入文件的文本数据,BUFFER的最大值是32767个字节。如果在open的时候没有指定值,默认是1024个字节,没有刷新到文件之前,一系列的WRITE操作的BUFFER总和不能超过32767个字节。

    说明:

    对于写操作,会检测写入文件类型,如果为elf类型文件,会报错退出。

  • DBE_FILE.NEW_LINE

    函数DBE_FILE.NEW_LINE用于向文件对应的缓冲区中写入一个或者多个行终结符,行终结符和平台相关。

    DBE_FILE.NEW_LINE函数原型为:

    1
    2
    3
    4
    DBE_FILE.NEW_LINE (
    file         IN     INTEGER,
    line_nums    IN     INTEGER := 1)
    RETURN BOOLEAN;
    
    表7 DBE_FILE.NEW_LINE接口参数说明

    参数

    类型

    入参/出参

    是否可以为空

    描述

    file

    INTEGER

    IN

    通过OPEN打开的文件句柄。

    line_nums

    INTEGER

    IN

    写入到文件中的终结符的数量,默认值为1。

  • DBE_FILE.WRITE_LINE

    函数DBE_FILE.WRITE_LINE用于向文件对应的缓冲区中写入BUFFER中的数据,文件必须以写模式打开,这个操作会自动追加行终结符。

    DBE_FILE.WRITE_LINE函数原型为:

    1
    2
    3
    4
    5
    DBE_FILE.WRITE_LINE(
    file       IN     INTEGER,
    buffer     IN     TEXT,
    flush      IN     BOOLEAN DEFAULT FALSE)
    RETURN BOOLEAN;
    
    表8 DBE_FILE.WRITE_LINE接口参数说明

    参数

    类型

    入参/出参

    是否可以为空

    描述

    file

    INTEGER

    IN

    通过OPEN打开的文件句柄。

    buffer

    TEXT

    IN

    要写入文件的文本数据,BUFFER的最大值是32767个字节。如果在open的时候没有指定值,默认是1024个字节,没有刷新到文件之前,一系列的PUT操作的BUFFER总和不能超过32767个字节。

    说明:

    对于写操作,会检测写入文件类型,如果为elf类型文件,会报错退出。

    flush

    BOOLEAN

    IN

    在write后是否要刷到磁盘。

  • DBE_FILE.FORMAT_WRITE

    函数DBE_FILE.FORMAT_WRITE将格式化数据写入到一个打开的文件对应的缓冲区中,是允许格式化的DBE_FILE.WRITE接口。

    DBE_FILE.FORMAT_WRITE函数原型为:

    1
    2
    3
    4
    5
    6
    7
    DBE_FILE.FORMAT_WRITE (
    file   IN INTEGER,
    format IN VARCHAR2,
    arg1  IN VARCHAR2 DEFAULT NULL,
    . . .
    arg6 IN VARCHAR2 DEFAULT NULL])
    RETURN BOOLEAN;
    
    表9 DBE_FILE.FORMAT_WRITE接口参数说明

    参数

    类型

    入参/出参

    是否可以为空

    描述

    file

    INTEGER

    IN

    通过OPEN打开的文件句柄。

    format

    TEXT

    IN

    一个要进行格式化的字符串包含,文本和格式符\n和%s。

    [arg1. . .arg6]

    TEXT

    IN

    从1到6个可选的参数串,参数和格式化字符的位置是一一对应的,如果存在格式化字符而没有提供参数,会使用空串来替代%s。

  • DBE_FILE.GET_RAW

    该函数用于从打开的文件描述符中读取二进制数据,从r中返回。

    DBE_FILE.GET_RAW函数原型为:

    1
    2
    3
    4
    5
    DBE_FILE.GET_RAW (
    file    IN   INTEGER,
    r       OUT  RAW,
    length  IN   INTEGER DEFAULT NULL)
    RETURN RAW;
    
    表10 DBE_FILE.GET_RAW接口参数说明

    参数

    类型

    入参/出参

    是否可以为空

    描述

    file

    INTEGER

    IN

    通过OPEN打开的文件句柄。

    r

    RAW

    OUT

    输出的二进制数据

    length

    INTEGER

    IN

    要读取文件的长度,默认值为NULL,读取文件中所有数据,最大长度为1G。

  • DBE_FILE.PUT_RAW

    函数DBE_FILE.PUT_RAW用于向文件对应的缓冲区中写入RAW类型数据。

    DBE_FILE.PUT_RAW函数原型为:

    1
    2
    3
    4
    5
    DBE_FILE.PUT_RAW (
    file    IN  INTEGER,
    r       IN  RAW,
    flush   IN  BOOLEAN DEFAULT FALSE)
    RETURN BOOLEAN;
    
    表11 DBE_FILE.PUT_RAW接口参数说明

    参数

    类型

    入参/出参

    是否可以为空

    描述

    file

    INTEGER

    IN

    通过OPEN打开的文件句柄。

    r

    RAW

    IN

    输出的二进制数据

    说明:

    对于写操作,会检测写入文件类型,如果为elf类型文件,会报错退出。

    flush

    BOOLEAN

    IN

    是否flush到文件中,默认为false。

  • DBE_FILE.FLUSH

    函数DBE_FILE.FLUSH将缓冲区中的数据写入到物理文件中,缓存中的数据必须要有一个行终结符。该函数可以将缓冲区的数据及时写入到对应的物理文件中。

    DBE_FILE.FLUSH函数原型为:

    1
    2
    3
    DBE_FILE.FLUSH (
    file     IN     INTEGER)
    RETURN VOID;
    
    表12 DBE_FILE.FLUSH接口参数说明

    参数

    类型

    入参/出参

    是否可以为空

    描述

    file

    INTEGER

    IN

    一个打开的文件句柄。

  • DBE_FILE.CLOSE

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

    DBE_FILE.CLOSE函数原型为:

    1
    2
    3
    DBE_FILE.CLOSE (
    file IN INTEGER
    )RETURN INTEGER;
    
    表13 DBE_FILE.CLOSE接口参数说明

    参数

    类型

    入参/出参

    是否可以为空

    描述

    file

    INTEGER

    IN

    通过OPEN打开的文件句柄。

  • DBE_FILE.CLOSE_ALL

    函数DBE_FILE.CLOSE_ALL关闭一个会话中打开的所有的文件句柄,可用于紧急的清理操作。

    DBE_FILE.CLOSE_ALL函数原型为:

    1
    2
    DBE_FILE.CLOSE_ALL()
    RETRUN VOID;
    
    表14 DBE_FILE.CLOSE_ALL接口参数说明

    参数

    描述

  • DBE_FILE.REMOVE

    函数DBE_FILE.REMOVE删除一个磁盘文件,使用的时候需要有充分的权限。

    DBE_FILE.REMOVE函数原型为:

    1
    2
    3
    4
    DBE_FILE.REMOVE (
    dir           IN     VARCHAR2,
    file_name     IN     VARCHAR2)
    RETURN VOID;
    
    表15 DBE_FILE.REMOVE接口参数说明

    参数

    类型

    入参/出参

    是否可以为空

    描述

    dir

    VARCHAR2

    IN

    文件的目录位置,这个字符串是一个目录对象名。

    说明:
    • 文件目录的位置,需要添加到系统表PG_DIRECTORY中,如果传入的路径和PG_DIRECTORY中的路径不匹配,会报路径不存在的错误,下面的涉及location作为参数的函数也是同样的情况。
    • 在打开guc参数safe_data_path时,用户只能通过高级包读写safe_data_path指定文件路径下的文件。

    file_name

    VARCHAR2

    IN

    文件名。

  • DBE_FILE.RENAME

    函数DBE_FILE.RENAME重命名一个磁盘文件,类似Unix的mv指令。

    DBE_FILE.RENAME函数原型为:

    1
    2
    3
    4
    5
    6
    7
    DBE_FILE.RENAME (
    src_dir        IN   VARCHAR2,
    src_file_name  IN   VARCHAR2,
    dest_dir       IN   VARCHAR2,
    dest_file_name IN   VARCHAR2,
    overwrite      IN   BOOLEAN DEFAULT FALSE)
    RETURN VOID;
    
    表16 DBE_FILE.RENAME接口参数说明

    参数

    类型

    入参/出参

    是否可以为空

    描述

    src_dir

    VARCHAR2

    IN

    源文件的目录位置(大小写敏感)。

    说明:
    • 文件目录的位置,需要添加到系统表PG_DIRECTORY中,如果传入的路径和PG_DIRECTORY中的路径不匹配,会报路径不存在的错误,下面的涉及location作为参数的函数也是同样的情况。
    • 在打开guc参数safe_data_path时,用户只能通过高级包读写safe_data_path指定文件路径下的文件。

    src_file_name

    VARCHAR2

    IN

    要进行命名的源文件。

    dest_dir

    VARCHAR2

    IN

    目的目录位置(大小写敏感)。

    说明:
    • 文件目录的位置,需要添加到系统表PG_DIRECTORY中,如果传入的路径和PG_DIRECTORY中的路径不匹配,会报路径不存在的错误,下面的涉及location作为参数的函数也是同样的情况。
    • 在打开guc参数safe_data_path时,用户只能通过高级包读写safe_data_path指定文件路径下的文件。

    dest_file_name

    VARCHAR2

    IN

    新的文件名。

    overwrite

    BOOLEAN

    IN

    是否重写,参数指定为空或者不指定时表示不重写。在不重写的情况下,如果目的目录下已存在同名文件会报错。

  • DBE_FILE.COPY

    函数DBE_FILE.COPY复制一个连续区域的内容到一个新创建的文件中,如果忽略了start_line和end_line会复制整个文件。

    DBE_FILE.COPY函数原型为:

    1
    2
    3
    4
    5
    6
    7
    8
    DBE_FILE.COPY (
    src_dir           IN     VARCHAR2,
    src_file_name     IN     VARCHAR2,
    dest_dir          IN     VARCHAR2,
    dest_file_name    IN     VARCHAR2,
    start_line        IN     INTEGER DEFAULT 1,
    end_line          IN     INTEGER DEFAULT NULL)
    RETURN VOID;
    
    表17 DBE_FILE.COPY接口参数说明

    参数

    类型

    入参/出参

    是否可以为空

    描述

    src_dir

    VARCHAR2

    IN

    源文件所在的目录。

    说明:
    • 文件目录的位置,需要添加到系统表PG_DIRECTORY中,如果传入的路径和PG_DIRECTORY中的路径不匹配,会报路径不存在的错误,下面的涉及location作为参数的函数也是同样的情况。
    • 在打开guc参数safe_data_path时,用户只能通过高级包读写safe_data_path指定文件路径下的文件。

    src_file_name

    VARCHAR2

    IN

    要拷贝的源文件。

    dest_dir

    VARCHAR2

    IN

    目的文件所在的目录。

    说明:
    • 文件目录的位置,需要添加到系统表PG_DIRECTORY中,如果传入的路径和PG_DIRECTORY中的路径不匹配,会报路径不存在的错误,下面的涉及location作为参数的函数也是同样的情况。
    • 在打开guc参数safe_data_path时,用户只能通过高级包读写safe_data_path指定文件路径下的文件。

    dest_file_name

    VARCHAR2

    IN

    目的文件名。

    说明:

    对于写操作,会检测写入文件类型,如果为elf类型文件,会报错退出。

    start_line

    INTEGER

    IN

    拷贝开始的行号,默认是1。

    end_line

    INTEGER

    IN

    拷贝结束的行号,默认是NULL,如果是NULL,则指定到文件尾。

  • DBE_FILE.GET_ATTR

    函数DBE_FILE.GET_ATTR读取并返回一个磁盘文件的属性。

    DBE_FILE.GET_ATTR函数原型为:

    1
    2
    3
    4
    5
    6
    DBE_FILE.GET_ATTR(
    location IN text,
    filename IN text,
    OUT fexists boolean,
    OUT file_length bigint,
    OUT block_size integer);
    
    表18 DBE_FILE.GET_ATTR接口参数说明

    参数

    类型

    入参/出参

    是否可以为空

    描述

    location

    TEXT

    IN

    文件所在的目录。

    说明:
    • 文件目录的位置,需要添加到系统表PG_DIRECTORY中,如果传入的路径和PG_DIRECTORY中的路径不匹配,会报路径不存在的错误,下面的涉及location作为参数的函数也是同样的情况。
    • 在打开guc参数safe_data_path时,用户只能通过高级包读写safe_data_path指定文件路径下的文件。

    filename

    TEXT

    IN

    文件名。

    fexists

    BOOLEAN

    OUT

    文件是否存在。

    file_length

    BIGINT

    OUT

    文件的字节长度,如果文件不存在返回NULL。

    block_size

    INTEGER

    OUT

    文件系统的块大小(单位字节),如果文件不存在返回NULL。

  • DBE_FILE.SEEK

    函数DBE_FILE.SEEK根据用户指定的字节数向前或者向后调整文件指针的位置。

    DBE_FILE.SEEK函数原型为:

    1
    2
    3
    4
    5
    DBE_FILE.SEEK (
    file            IN INTEGER,
    absolute_start  IN     BIGINT DEFAULT NULL,
    relative_start  IN     BIGINT DEFAULT NULL)
    RETURN VOID;
    
    表19 DBE_FILE.SEEK接口参数说明

    参数

    类型

    入参/出参

    是否可以为空

    描述

    file

    INTEGER

    IN

    通过OPEN打开的文件句柄。

    absolute_start

    BIGINT

    IN

    文件偏移的绝对位置,默认值为NULL。

    relative_start

    BIGINT

    IN

    文件偏移的相对位置。如果这个值是正数,向前偏移;如果是负数,向后偏移;默认值为NULL。如果和absolute_start参数同时指定,以absolute_start参数为准。

  • DBE_FILE.GET_POS

    函数DBE_FILE.GET_POS以字节为单位返回文件当前的偏移量。

    DBE_FILE.FGETPOS函数原型为:

    1
    2
    3
    DBE_FILE.GET_POS (
    file    IN     INTEGER)
    RETURN BIGINT;
    
    表20 DBE_FILE.GET_POS接口参数说明

    参数

    类型

    入参/出参

    是否可以为空

    描述

    file

    INTEGER

    IN

    通过OPEN打开的文件句柄。

示例

 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
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
--系统管理员向PG_DIRECTORY系统表中加入目录/temp/:
CREATE OR REPLACE DIRECTORY dir AS '/tmp/';
-- 预期结果为:
CREATE DIRECTORY

--打开一个文件并向文件中写入数据                                                                                                                   
DECLARE
  f integer;
  dir text := 'dir';
BEGIN
  f := dbe_file.open(dir, 'sample.txt', 'w');
  PERFORM dbe_file.write_line(f, 'ABC');
  PERFORM dbe_file.write_line(f, '123'::numeric);
  PERFORM dbe_file.write_line(f, '-----');
  PERFORM dbe_file.new_line(f);
  PERFORM dbe_file.write_line(f, '*******');
  PERFORM dbe_file.new_line(f, 0);
  PERFORM dbe_file.write_line(f, '++++++++');
  PERFORM dbe_file.new_line(f, 2);
  PERFORM dbe_file.write_line(f, '#######');
  PERFORM dbe_file.write(f, 'A');
  PERFORM dbe_file.write(f, 'B');
  PERFORM dbe_file.new_line(f);
  PERFORM dbe_file.format_write(f, '[1 -> %s, 2 -> %s, 3 -> %s, 4 -> %s, 5 -> %s]', 'gaussdb', 'dbe', 'file', 'get', 'line');
  PERFORM dbe_file.new_line(f);
  PERFORM dbe_file.write_line(f, '1234567890');
  f := dbe_file.close(f);
END;
/
-- 预期结果为:
ANONYMOUS BLOCK EXECUTE

--在上面写入的文件中读取数据。
DECLARE
  f integer;
  dir text := 'dir';
BEGIN
  f := dbe_file.open(dir, 'sample.txt', 'r');
  FOR i IN 1..11 LOOP
       RAISE INFO '[%] : %', i, dbe_file.read_line(f);
  END LOOP;
END;
/
-- 预期结果为:
INFO:  [1] : ABC
INFO:  [2] : 123
INFO:  [3] : -----
INFO:  [4] : 
INFO:  [5] : *******
INFO:  [6] : ++++++++
INFO:  [7] : 
INFO:  [8] : 
INFO:  [9] : #######
INFO:  [10] : AB
INFO:  [11] : [1 -> gaussdb, 2 -> dbe, 3 -> file, 4 -> get, 5 -> line]
ANONYMOUS BLOCK EXECUTE

-- 对文件句柄执行位置偏移,并获取文件的当前位置。                                                                                                 
DECLARE
      l_file   integer;
      l_buffer VARCHAR2(32767);
      dir text := 'dir';
      abs_offset number := 100;
      rel_offset number := NULL;
BEGIN
      l_file := dbe_file.open(dir  => dir,  file_name  => 'sample.txt',open_mode => 'R');
      dbe_output.print_line('before seek: current position is ' || dbe_file.get_pos(file => l_file)); -- before seek: current position is 0
      dbe_file.seek(file => l_file, absolute_start=>abs_offset, relative_start=>rel_offset);
      dbe_output.print_line('fseek: current position is ' || dbe_file.get_pos(file => l_file)); -- seek: current position is 100
      l_file := dbe_file.close(file => l_file);
END;
/
-- 预期结果为:
before seek: current position is 0
fseek: current position is 100
ANONYMOUS BLOCK EXECUTE

相关文档