云数据库 GaussDB-DBE_FILE:接口介绍
接口介绍
高级功能包DBE_FILE支持的所有接口请参见表 DBE_FILE。
接口名称 |
描述 |
---|---|
根据指定的目录和文件名打开一个文件。 |
|
检测一个文件句柄是否打开。 |
|
根据指定的长度从一个打开的文件句柄中读取出一行数据。 |
|
将BUFFER中指定的数据写入到文件中。 |
|
这个存储过程用于向一个打开的文件中写入一个或者多个行终结符。 |
|
这个存储过程将BUFFER中的字符串写入到一个打开的文件中。 |
|
这个存储过程是一个格式化的PUT存储过程,行为类似printf()。 |
|
从一个打开的文件句柄中读取二进制数据。 |
|
向文件中写入传入的二进制数据。 |
|
将一个文件句柄中的数据写入到物理文件中。 |
|
关闭一个打开的文件句柄。 |
|
关闭一个会话中打开的所有的文件句柄。 |
|
这个存储过程删除一个磁盘文件,操作的时候需要有充分的权限。 |
|
对于磁盘上的文件进行重命名,类似Unix的mv。 |
|
拷贝一个连续的区域内容到一个新创建的文件中,如果忽略了start_line和end_line会拷贝整个文件。 |
|
读取并返回磁盘文件的属性。 |
|
根据用户指定的字节数向前或者向后调整文件指针的位置。 |
|
返回文件的偏移量,单位字节。 |
- DBE_FILE.OPEN
该函数用来打开一个文件,可以指定最大行的大小,最多可以同时打开50个文件。并且该函数返回INTEGER类型的一个句柄。
DBE_FILE.OPEN函数原型为:
123456
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
文件的目录位置,这个字符串是一个目录对象名。
说明:文件目录的位置,需要添加到系统表PG_DIRECTORY中,如果传入的路径和PG_DIRECTORY中的路径不匹配,会报路径不存在的错误, 下面的涉及location作为参数的函数也是同样的情况。
file_name
文件名,包含扩展(文件类型),不包括路径名。如果文件名中包含路径,在OPEN中会被忽略,在Unix系统中,文件名不能以/.结尾。
open_mode
指定文件的打开模式,包含r:read text,w: write text和a: append text。
说明:对于写操作,会检测写入文件类型,如果为elf类型文件,会报错退出。
max_line_size
每行最大字符数,包含换行符(最小值是1,最大值是32767)。如果没有指定,会指定一个默认值1024。
- DBE_FILE.IS_CLOSE
该函数用于检测一个文件句柄来查看文件是否已经打开,返回一个布尔值,异常情况是INVALID_FILEHANDLE。
DBE_FILE.IS_CLOSE函数原型为:
123
DBE_FILE.IS_CLOSE (file IN INTEGERINTEGER)RETURN BOOLEAN;
表3 DBE_FILE.IS_CLOSE接口参数说明 参数
描述
file IN INTEGERINTEGER
传入一个要检测的文件句柄。
- DBE_FILE.READ_LINE
该存储过程从一个打开的文件句柄中读取文本,并把读取的结果存放到BUFFER中。读取的时候会读取到行尾,不包含行终结符或者读取到文件末尾,或者达到了len参数指定的大小,读取的长度不能超过OPEN的时候指定的max_line_size。
DBE_FILE.READ_LINE函数原型为:
1234
DBE_FILE.READ_LINE (file IN INTEGER,buffer OUT VARCHAR2,len IN INTEGER DEFAULT NULL)
表4 DBE_FILE.READ_LINE接口参数说明 参数
描述
file
通过调用OPEN打开的文件句柄,文件必须以读的模式打开,否则会抛出INVALID_OPERATION的异常。
buffer
用于接收数据的BUFFER。
len
从文件中读取的字节数,默认是NULL。如果是默认NULL,会使用max_linesize来指定大小。
- DBE_FILE.WRITE
该存储过程用于向文件中写入BUFFER中的数据,要写入的文件必须以写模式打开,这个操作不会写入行终结符。
DBE_FILE.WRITE函数原型为:
123
DBE_FILE.WRITE (file IN INTEGERINTEGER,buffer IN VARCHAR2);
表5 DBE_FILE.WRITE接口参数说明 参数
描述
file
该存储过程用于向文件中写入BUFFER中的数据,要写入的文件必须以写模式打开,这个操作不会写入行终结符。
buffer
要写入文件的文本数据,BUFFER的最大值是32767个字节。如果在open的时候没有指定值,默认是1024个字节,没有刷新到文件之前,一系列的WRITE操作的BUFFER总和不能超过32767个字节。
说明:对于写操作,会检测写入文件类型,如果为elf类型文件,会报错退出。
- DBE_FILE.NEW_LINE
该存储过程用于向一个打开的文件中写入一个或者多个行终结符。这个存储过程是从WRITE函数中拆分出来的,因为行终结符和平台相关。
DBE_FILE.NEW_LINE函数原型为:
123
DBE_FILE.NEW_LINE (file IN INTEGER,line_nums IN INTEGER := 1);
表6 DBE_FILE.NEW_LINE接口参数说明 参数
描述
file
一个打开的文件句柄。
line_nums
写入到文件中的终结符的数量。
- DBE_FILE.WRITE_LINE
该存储过程将BUFFER中的字符串写入到一个打开的文件中,文件必须以写模式打开。
DBE_FILE.WRITE_LINE函数原型为:
1234
DBE_FILE.WRITE_LINE(file IN INTEGER,buffer IN VARCHAR2,flush IN BOOLEAN DEFAULT FALSE);
表7 DBE_FILE.WRITE_LINE接口参数说明 参数
描述
file
一个打开的文件句柄。
buffer
要写入文件的文本数据,BUFFER的最大值是32767个字节。如果在open的时候没有指定值,默认是1024个字节,没有刷新到文件之前,一系列的PUT操作的BUFFER总和不能超过32767个字节。
说明:对于写操作,会检测写入文件类型,如果为elf类型文件,会报错退出。
flush
在write后是否要刷到磁盘。
- DBE_FILE.FORMAT_WRITE
该存储过程是一个格式化的PUT存储过程,行为类似printf()。
DBE_FILE.FORMAT_WRITE函数原型为:
123456
DBE_FILE.FORMAT_WRITE (file IN INTEGER,format IN VARCHAR2,arg1 IN VARCHAR2 DEFAULT NULL,. . .arg5 IN VARCHAR2 DEFAULT NULL]);
表8 DBE_FILE.FORMAT_WRITE接口参数说明 参数
描述
file
一个打开的文件句柄。
format
一个要进行格式化的字符串包含,文本和格式符\n和%s。
[arg1. . .arg5]
从1到5个可选的参数串,参数和格式化字符的位置是一一对应的,如果存在格式化字符而没有提供参数,会使用空串来替代%s。
- DBE_FILE.GET_RAW
DBE_FILE.GET_RAW函数原型为:
1234
DBE_FILE.GET_RAW (file IN INTEGER,r OUT RAW,length IN INTEGER DEFAULT NULL);
表9 DBE_FILE.GET_RAW接口参数说明 参数
描述
file
一个打开的文件句柄。
r
输出的二进制数据
length
要读取文件的长度,默认值为NULL,读取文件中所有数据,最大长度为1G。
- DBE_FILE.PUT_RAW
DBE_FILE.PUT_RAW函数原型为:
1234
DBE_FILE.GET_RAW (file IN INTEGER,r IN RAW,flush IN BOOLEAN DEFAULT FALSE);
表10 DBE_FILE.PUT_RAW接口参数说明 参数
描述
file
一个打开的文件句柄。
r
输出的二进制数据
说明:对于写操作,会检测写入文件类型,如果为elf类型文件,会报错退出。
flush
是否flush到文件中,默认为false。
- DBE_FILE.FLUSH
一个文件句柄中的数据要写入到物理文件中,缓冲区中的数据必须要有一个行终结符。当文件必须在打开时读取,刷新非常有用。例如,调试信息可以刷新到文件中,以便立即读取。
DBE_FILE.FLUSH函数原型为:
12
DBE_FILE.FLUSH (file IN INTEGER);
表11 DBE_FILE.FLUSH接口参数说明 参数
描述
file
一个打开的文件句柄。
- DBE_FILE.CLOSE
该存储过程用于关闭一个打开的文件句柄,当调用这个存储过程的时候,如果还有等待写入的缓存的数据,可能会收到异常信息。
DBE_FILE.CLOSE函数原型为:
12
DBE_FILE.CLOSE (file IN OUT INTEGER);
表12 DBE_FILE.CLOSE接口参数说明 参数
描述
file
一个打开的文件句柄。
- DBE_FILE.CLOSE_ALL
该存储过程关闭一个会话中打开的所有的文件句柄,可用于紧急的清理操作。
DBE_FILE.CLOSE_ALL函数原型为:
1
DBE_FILE.CLOSE_ALL;
表13 DBE_FILE.CLOSE_ALL接口参数说明 参数
描述
无
无
- DBE_FILE.REMOVE
该存储过程删除一个磁盘文件,操作的时候对目录和文件要有充分的权限。
DBE_FILE.REMOVE函数原型为:
123
DBE_FILE.REMOVE (dir IN VARCHAR2,file_name IN VARCHAR2);
表14 DBE_FILE.REMOVE接口参数说明 参数
描述
dir
文件所在的目录位置。
file_name
要删除的文件。
- DBE_FILE.RENAME
DBE_FILE.RENAME函数原型为:
123456
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);
表15 DBE_FILE.RENAME接口参数说明 参数
描述
src_dir
原文件的目录位置(大小写敏感)。
src_file_name
要进行命名的原文件。
dest_dir
目的目录(大小写敏感)。
dest_file_name
新的文件名。
overwrite
默认是false,如果目的目录下存在一个同名的文件,不会进行重写。
- DBE_FILE.COPY
该存储过程拷贝一个连续的区域内容到一个新创建的文件中,如果忽略了start_line和end_line会拷贝整个文件。
DBE_FILE.COPY函数原型为:
1234567
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);
表16 DBE_FILE.COPY接口参数说明 参数
描述
src_dir
原文件所在的目录。
src_file_name
要拷贝的原文件。
dest_dir
目的文件所在的目录。
dest_file_name
要写入的目的文件。
说明:对于写操作,会检测写入文件类型,如果为elf类型文件,会报错退出。
start_line
拷贝开始的行号,默认是1。
end_line
拷贝结束的行号,默认是NULL,指定到文件尾。
- DBE_FILE.GET_ATTR
DBE_FILE.FGETATTR函数原型为:
123456
DBE_FILE.GET_ATTR(dir IN VARCHAR2,file_name IN VARCHAR2,is_exists OUT BOOLEAN,length OUT NUMBER,block_size OUT INTEGER);
表17 DBE_FILE.GET_ATTR接口参数说明 参数
描述
dir
文件所在的目录。
file_name
要检测的文件名。
is_exists
返回文件是否存在的值。
length
文件的字节长度,如果文件不存在返回NULL。
block_size
文件系统的块大小(单位字节),如果文件不存在返回NULL。
- DBE_FILE.SEEK
该存储过程会根据用户指定的字节数向前或者向后调整文件指针的位置。
DBE_FILE.SEEK函数原型为:
1234
DBE_FILE.SEEK (file INOUT DBE_FILE.FILE_TYPE,absolute_start IN INTEGER DEFAULT NULL,relative_start IN INTEGER DEFAULT NULL);
表18 DBE_FILE.SEEK接口参数说明 参数
描述
file
一个打开的文件句柄。
absolute_start
文件偏移的绝对位置,这个默认值为NULL。
relative_start
文件偏移的相对位置。如果这个值是正数,向前偏移;如果是负数,向后偏移;默认值为NULL。如果和absolute_offset参数同时指定,以absolute_offset参数为准。
- DBE_FILE.GET_POS
DBE_FILE.FGETPOS函数原型为:
123
DBE_FILE.GET_POS (file IN INTEGER)RETURN BIGINT;
表19 DBE_FILE.GET_POS接口参数说明 参数
描述
file
一个打开的文件句柄。