DBE_FILE
DBE_FILE包为存储过程提供了读、写操作系统文本文件的能力。
接口介绍
高级功能包DBE_FILE支持的所有接口请参见表1。
接口名称 |
描述 |
---|---|
根据指定的目录和文件名打开一个文件。 |
|
检测一个文件句柄是否关闭。 |
|
检测一个文件句柄是否打开。 |
|
从一个打开的文件句柄中读取一行指定长度的数据。 |
|
将数据写入到一个打开的文件的缓冲区中。 |
|
将一个或者多个行终结符写入到一个打开的文件的缓冲区中。 |
|
将数据写入到一个打开的文件的缓冲区中,并自动追加一个行终结符。 |
|
将数据按指定格式写入到一个打开的文件的缓冲区中。 |
|
从一个打开的文件中读取指定字节数的RAW类型数据。 |
|
将RAW类型数据写入到一个打开的文件的缓冲区中。 |
|
将缓存区中的数据写入到物理文件中。 |
|
关闭一个打开的文件句柄。 |
|
关闭一个会话中打开的所有的文件句柄。 |
|
根据指定的目录和文件名删除一个磁盘文件,操作的时候需要有充分的权限。 |
|
重命名一个磁盘文件,类似Unix的mv指令。 |
|
复制一个连续区域的内容到一个新创建的文件中,如果忽略了start_line和end_line会复制整个文件。 |
|
读取并返回一个磁盘文件的属性。 |
|
根据用户指定的字节数向前或者向后调整文件指针的位置。 |
|
以字节为单位返回文件当前的偏移量。 |
- 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
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 |