接口介绍

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

• DBE_FILE.OPEN/DBE_FILE.FOPEN

  函数DBE_FILE.OPEN用来打开一个文件，可以指定最大行的大小，一个会话内最多可以同时打开50个文件。该函数返回一个INTEGER类型的文件句柄。函数DBE_FILE.FOPEN功能和DBE_FILE.OPEN类似，返回一个DBE_FILE.FILE_TYPE类型的对象。

  DBE_FILE.OPEN函数原型为：

  1 2 3 4 5 6 7 8 9 10 11 12 13

  DBE_FILE.OPEN( dir IN TEXT, file_name IN TEXT, open_mode IN TEXT, max_line_size IN INTEGER DEFAULT 1024) RETURN INTEGER; DBE_FILE.FOPEN( dir IN TEXT, file_name IN TEXT, open_mode IN TEXT, max_line_size IN INTEGER DEFAULT 1024) RETURN DBE_FILE.FILE_TYPE;

  表3 DBE_FILE.OPEN/DBE_FILE.FOPEN接口参数说明

  参数	描述
  dir	文件的目录位置，这个字符串是一个目录对象名。 说明： 文件目录的位置，需要添加到系统表PG_DIRECTORY中，如果传入的路径和PG_DIRECTORY中的路径不匹配，会报路径不存在的错误。 在打开guc参数safe_data_path时，用户只能通过高级包读写safe_data_path指定文件路径下的文件。
  file_name	文件名，包含扩展（文件类型），不包括路径名。如果文件名中包含路径，在OPEN中会被忽略，在Unix系统中，文件名不能以/.结尾。
  open_mode	指定文件的打开模式，包含r：read text，w: write text, a: append text, rb: read byte, wb: write byte和ab: append byte。 说明： 对于写操作，会检测写入文件类型，如果为elf类型文件，会报错退出。
  max_line_size	每行最大字符数，包含换行符（最小值是1，最大值是32767）。如果没有指定，会指定一个默认值1024。

• DBE_FILE.IS_CLOSE

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

  DBE_FILE.IS_CLOSE函数原型为：

  1 2 3 4 5 6 7

  DBE_FILE.IS_CLOSE( file IN INTEGER) RETURN BOOLEAN; DBE_FILE.IS_CLOSE( file IN DBE_FILE.FILE_TYPE) RETURN BOOLEAN;

  表4 DBE_FILE.IS_CLOSE接口参数说明

  参数	描述
  file	待检测的文件句柄或DBE_FILE.FILE_TYPE类型的对象。

• DBE_FILE.IS_OPEN

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

  DBE_FILE.IS_OPEN函数原型为：

  1 2 3 4 5 6 7

  DBE_FILE.IS_OPEN( file IN INTEGER) RETURN BOOLEAN; DBE_FILE.IS_OPEN( file IN DBE_FILE.FILE_TYPE) RETURN BOOLEAN;

  表5 DBE_FILE.IS_OPEN接口参数说明

  参数	描述
  file	待检测的文件句柄或DBE_FILE.FILE_TYPE类型的对象。

• DBE_FILE.READ_LINE

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

  DBE_FILE.READ_LINE存储过程原型为：

  1 2 3 4 5 6 7 8 9

  DBE_FILE.READ_LINE( file IN INTEGER, buffer OUT TEXT, len IN INTEGER DEFAULT NULL); DBE_FILE.READ_LINE( file IN DBE_FILE.FILE_TYPE, buffer OUT TEXT, len IN INTEGER DEFAULT NULL);

  表6 DBE_FILE.READ_LINE接口参数说明

  参数	描述
  file	通过OPEN打开的文件句柄或者FOPEN打开的DBE_FILE.FILE_TYPE类型的对象，文件必须以读模式打开，否则会抛出INVALID_OPERATION的异常。
  buffer	接收数据的buffer。
  len	从文件中读取的字节数，默认值为NULL。如果是NULL，会使用max_line_size来指定大小。

• DBE_FILE.WRITE

  函数DBE_FILE.WRITE用于向文件中写入buffer中的数据，文件必须以写模式打开，这个操作不会写入行终结符，返回值永远为TRUE。

  DBE_FILE.WRITE函数原型为：

  1 2 3 4 5 6 7 8 9

  DBE_FILE.WRITE( file IN INTEGER, buffer IN TEXT) RETURN BOOLEAN; DBE_FILE.WRITE( file IN DBE_FILE.FILE_TYPE, buffer IN TEXT) RETURN VOID;

  表7 DBE_FILE.WRITE接口参数说明

  参数	描述
  file	通过OPEN打开的文件句柄或者FOPEN打开的DBE_FILE.FILE_TYPE类型的对象，要写入的文件必须以写模式打开，这个操作不会写入行终结符。
  buffer	写入文件的文本数据。每行的累计写入长度不能大于或等于OPEN或FOPEN时指定或默认的max_line_size，否则会在刷新到文件时报错。 说明： 对于写操作，会检测写入文件类型，如果为elf类型文件，会报错退出。

• DBE_FILE.NEW_LINE

  函数DBE_FILE.NEW_LINE用于向一个打开的文件中写入一个或者多个行终结符。行终结符和平台相关，返回值永远为TRUE。

  DBE_FILE.NEW_LINE函数原型为：

  1 2 3 4 5 6 7 8 9

  DBE_FILE.NEW_LINE( file IN INTEGER, line_nums IN INTEGER DEFAULT 1) RETURN BOOLEAN; DBE_FILE.NEW_LINE( file IN DBE_FILE.FILE_TYPE, line_nums IN INTEGER DEFAULT 1) RETURN VOID;

  表8 DBE_FILE.NEW_LINE接口参数说明

  参数	描述
  file	通过OPEN打开的文件句柄或者FOPEN打开的DBE_FILE.FILE_TYPE类型的对象。
  line_nums	写入到文件中的行终结符的数量。

• DBE_FILE.WRITE_LINE

  函数DBE_FILE.WRITE_LINE用于向文件中写入buffer中的数据，文件必须以写模式打开，这个操作会自动追加行终结符，返回值永远为TRUE。

  DBE_FILE.WRITE_LINE函数原型为：

  1 2 3 4 5 6 7 8 9 10 11

  DBE_FILE.WRITE_LINE( file IN INTEGER, buffer IN TEXT, flush IN BOOLEAN DEFAULT FALSE) RETURN BOOLEAN; DBE_FILE.WRITE_LINE( file IN DBE_FILE.FILE_TYPE, buffer IN TEXT, flush IN BOOLEAN DEFAULT FALSE) RETURN VOID;

  表9 DBE_FILE.WRITE_LINE接口参数说明

  参数	描述
  file	通过OPEN打开的文件句柄或者FOPEN打开的DBE_FILE.FILE_TYPE类型的对象。
  buffer	要写入文件的文本数据，每行的长度（包含换行符）不能大于OPEN或FOPEN时指定或默认的max_line_size，否则会在刷新到文件时报错。 说明： 对于写操作，会检测写入文件类型，如果为elf类型文件，会报错退出。
  flush	在WRITE_LINE后是否要刷到磁盘，默认值为FALSE。

• DBE_FILE.FORMAT_WRITE

  函数DBE_FILE.FORMAT_WRITE将格式化数据写入到一个打开的文件，是允许格式化的DBE_FILE.WRITE接口，返回值永远为TRUE。

  DBE_FILE.FORMAT_WRITE函数原型为：

  1 2 3 4 5 6 7 8 9 10 11 12 13 14 15

  DBE_FILE.FORMAT_WRITE( file IN INTEGER, format IN TEXT, arg1 IN TEXT DEFAULT NULL, . . . arg6 IN TEXT DEFAULT NULL) RETURN BOOLEAN; DBE_FILE.FORMAT_WRITE( file IN DBE_FILE.FILE_TYPE, format IN TEXT, arg1 IN TEXT DEFAULT NULL, . . . arg6 IN TEXT DEFAULT NULL) RETURN VOID;

  表10 DBE_FILE.FORMAT_WRITE接口参数说明

  参数	描述
  file	通过OPEN打开的文件句柄或者FOPEN打开的DBE_FILE.FILE_TYPE类型的对象。
  format	格式化的字符串，包含文本和格式符\n和%s。
  [arg1. . .arg6]	从1到6个可选的参数串，参数和格式化字符的位置是一一对应的，如果存在格式化字符而没有提供参数，会使用空串来替代%s。

• DBE_FILE.GET_RAW

  存储过程DBE_FILE.GET_RAW从一个打开的文件读取RAW类型数据，并把读取的结果存放到buffer中，从r中返回。

  DBE_FILE.GET_RAW存储过程原型为：

  1 2 3 4 5 6 7 8 9

  DBE_FILE.GET_RAW( file IN INTEGER, r OUT RAW, length IN INTEGER DEFAULT NULL); DBE_FILE.GET_RAW( file IN DBE_FILE.FILE_TYPE, r OUT RAW, length IN INTEGER DEFAULT NULL);

  表11 DBE_FILE.GET_RAW接口参数说明

  参数	描述
  file	通过OPEN打开的文件句柄或者FOPEN打开的DBE_FILE.FILE_TYPE类型的对象。
  r	接收RAW类型数据的buffer。
  length	从文件中读取的字节数，默认值为NULL，如果是NULL，会使用RAW类型最大长度来指定大小。

• DBE_FILE.PUT_RAW

  函数DBE_FILE.PUT_RAW用于向文件中写入RAW类型数据，返回值永远为TRUE。

  DBE_FILE.PUT_RAW函数原型为：

  1 2 3 4 5 6 7 8 9 10 11

  DBE_FILE.PUT_RAW ( file IN INTEGER, r IN RAW, flush IN BOOLEAN DEFAULT FALSE) RETURN BOOLEAN; DBE_FILE.PUT_RAW ( file IN DBE_FILE.FILE_TYPE, r IN RAW, flush IN BOOLEAN DEFAULT FALSE) RETURN VOID;

  表12 DBE_FILE.PUT_RAW接口参数说明

  参数	描述
  file	通过OPEN打开的文件句柄或者FOPEN打开的DBE_FILE.FILE_TYPE类型的对象。
  r	写入文件的RAW类型数据。 说明： 对于写操作，会检测写入文件类型，如果为elf类型文件，会报错退出。
  flush	在PUT_RAW后是否要刷到磁盘，默认值为FALSE。

• DBE_FILE.FLUSH

  函数DBE_FILE.FLUSH将缓存的数据写入到物理文件中，缓存中的数据必须要有一个行终结符。

  DBE_FILE.FLUSH函数原型为：

  1 2 3 4 5 6 7

  DBE_FILE.FLUSH( file IN INTEGER) RETURN VOID; DBE_FILE.FLUSH( file IN DBE_FILE.FILE_TYPE) RETURN VOID;

  表13 DBE_FILE.FLUSH接口参数说明

  参数	描述
  file	通过OPEN打开的文件句柄或者FOPEN打开的DBE_FILE.FILE_TYPE类型的对象。

• DBE_FILE.CLOSE

  函数DBE_FILE.CLOSE用于关闭一个打开的文件，当调用这个函数的时候，如果还有等待写入的缓存的数据，可能会收到异常信息，返回值永远为TRUE。

  DBE_FILE.CLOSE函数原型为：

  1 2 3 4 5 6 7

  DBE_FILE.CLOSE( file IN INTEGER) RETURN BOOLEAN; DBE_FILE.CLOSE( file IN DBE_FILE.FILE_TYPE) RETURN BOOLEAN;

  表14 DBE_FILE.CLOSE接口参数说明

  参数	描述
  file	通过OPEN打开的文件句柄或者FOPEN打开的DBE_FILE.FILE_TYPE类型的对象。

• DBE_FILE.CLOSE_ALL

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

  DBE_FILE.CLOSE_ALL函数原型为：

  1 2	DBE_FILE.CLOSE_ALL() RETRUN VOID;

  表15 DBE_FILE.CLOSE_ALL接口参数说明

  参数	描述
  无	无

• DBE_FILE.REMOVE

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

  DBE_FILE.REMOVE函数原型为：

  1 2 3 4

  DBE_FILE.REMOVE( dir IN TEXT, file_name IN TEXT) RETURN VOID;

  表16 DBE_FILE.REMOVE接口参数说明

  参数	描述
  dir	文件的目录位置，这个字符串是一个目录对象名。 说明： 文件目录的位置，需要添加到系统表PG_DIRECTORY中，如果传入的路径和PG_DIRECTORY中的路径不匹配，会报路径不存在的错误。 在打开guc参数safe_data_path时，用户只能通过高级包操作safe_data_path指定文件路径下的文件。
  file_name	文件名。

• DBE_FILE.RENAME

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

  DBE_FILE.RENAME函数原型为：

  1 2 3 4 5 6 7

  DBE_FILE.RENAME( src_dir IN TEXT, src_file_name IN TEXT, dest_dir IN TEXT, dest_file_name IN TEXT, overwrite IN BOOLEAN DEFAULT FALSE) RETURN VOID;

  表17 DBE_FILE.RENAME接口参数说明

  参数	描述
  src_dir	原文件的目录位置（大小写敏感）。 说明： 文件目录的位置，需要添加到系统表PG_DIRECTORY中，如果传入的路径和PG_DIRECTORY中的路径不匹配，会报路径不存在的错误。 在打开guc参数safe_data_path时，用户只能通过高级包操作safe_data_path指定文件路径下的文件。
  src_file_name	要进行命名的原文件。
  dest_dir	目的目录位置（大小写敏感）。 说明： 文件目录的位置，需要添加到系统表PG_DIRECTORY中，如果传入的路径和PG_DIRECTORY中的路径不匹配，会报路径不存在的错误。 在打开guc参数safe_data_path时，用户只能通过高级包操作safe_data_path指定文件路径下的文件。
  dest_file_name	新的文件名。
  overwrite	是否重写，默认值为FALSE，如果目的目录下存在一个同名的文件，不会进行重写。

• 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 TEXT, src_file_name IN TEXT, dest_dir IN TEXT, dest_file_name IN TEXT, start_line IN INTEGER DEFAULT 1, end_line IN INTEGER DEFAULT NULL) RETURN VOID;

  表18 DBE_FILE.COPY接口参数说明

  参数	描述
  src_dir	原文件所在的目录。 说明： 文件目录的位置，需要添加到系统表PG_DIRECTORY中，如果传入的路径和PG_DIRECTORY中的路径不匹配，会报路径不存在的错误。 在打开guc参数safe_data_path时，用户只能通过高级包操作safe_data_path指定文件路径下的文件。
  src_file_name	原文件。
  dest_dir	目的文件所在的目录。 说明： 文件目录的位置，需要添加到系统表PG_DIRECTORY中，如果传入的路径和PG_DIRECTORY中的路径不匹配，会报路径不存在的错误。 在打开guc参数safe_data_path时，用户只能通过高级包操作safe_data_path指定文件路径下的文件。
  dest_file_name	目的文件。 说明： 对于写操作，会检测写入文件类型，如果为elf类型文件，会报错退出。
  start_line	拷贝开始的行号，默认为1。
  end_line	拷贝结束的行号，默认为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, fexists OUT BOOLEAN, file_length OUT BIGINT, block_size OUT INTEGER);

  表19 DBE_FILE.GET_ATTR接口参数说明

  参数	描述
  location	文件所在的目录。 说明： 文件目录的位置，需要添加到系统表PG_DIRECTORY中，如果传入的路径和PG_DIRECTORY中的路径不匹配，会报路径不存在的错误。 在打开guc参数safe_data_path时，用户只能通过高级包操作safe_data_path指定文件路径下的文件。
  filename	文件名。
  fexists	返回文件是否存在。
  file_length	返回文件的字节长度，如果文件不存在返回NULL。
  block_size	返回文件系统的块大小（单位字节），如果文件不存在返回NULL。

• DBE_FILE.SEEK

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

  DBE_FILE.SEEK函数原型为：

  1 2 3 4 5 6 7 8 9 10 11

  DBE_FILE.SEEK( file IN INTEGER, absolute_start IN BIGINT DEFAULT NULL, relative_start IN BIGINT DEFAULT NULL) RETURN VOID; DBE_FILE.SEEK( file IN DBE_FILE.FILE_TYPE, absolute_start IN BIGINT DEFAULT NULL, relative_start IN BIGINT DEFAULT NULL) RETURN VOID;

  表20 DBE_FILE.SEEK接口参数说明

  参数	描述
  file	通过OPEN打开的文件句柄或者FOPEN打开的DBE_FILE.FILE_TYPE类型的对象。
  absolute_start	文件偏移的绝对位置，默认值为NULL。
  relative_start	文件偏移的相对位置。如果值是正数，向前偏移；如果是负数，向后偏移；默认值为NULL。如果和absolute_start参数同时指定，以absolute_start参数为准。

• DBE_FILE.GET_POS

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

  DBE_FILE.FGETPOS函数原型为：

  1 2 3 4 5 6 7

  DBE_FILE.GET_POS( file IN INTEGER) RETURN BIGINT; DBE_FILE.GET_POS( file IN DBE_FILE.FILE_TYPE) RETURN BIGINT;

  表21 DBE_FILE.GET_POS接口参数说明

  参数	描述
  file	通过OPEN打开的文件句柄或者FOPEN打开的DBE_FILE.FILE_TYPE类型的对象。

• DBE_FILE.FOPEN_NCHAR

  函数DBE_FILE.FOPEN_NCHAR用来打开一个文件，可以指定最大行的大小，一个会话内最多可以同时打开50个文件。该函数返回一个DBE_FILE.FILE_TYPE类型的文件句柄。该函数以国家字符集模式打开文件以进行输入或输出。

  DBE_FILE.FOPEN_NCHAR函数原型为：

  1 2 3 4 5 6

  DBE_FILE.FOPEN_NCHAR( dir IN TEXT, file_name IN TEXT, open_mode IN TEXT, max_line_size IN INTEGER DEFAULT 1024) RETURN DBE_FILE.FILE_TYPE;

  表22 DBE_FILE.FOPEN_NCHAR接口参数说明

  参数	描述
  dir	文件的目录位置，这个字符串是一个目录对象名。 说明： 文件目录的位置，需要添加到系统表PG_DIRECTORY中，如果传入的路径和PG_DIRECTORY中的路径不匹配，会报路径不存在的错误。 在打开guc参数safe_data_path时，用户只能通过高级包读写safe_data_path指定文件路径下的文件。
  file_name	文件名，包含扩展（文件类型），不包括路径名。如果文件名中包含路径，在FOPEN_NCHAR中会被忽略，在Unix系统中，文件名不能以/.结尾。
  open_mode	指定文件的打开模式，包含r：read text，w: write text, a: append text, rb: read byte, wb: write byte和ab: append byte。 说明： 对于写操作，会检测写入文件类型，如果为elf类型文件，会报错退出。
  max_line_size	每行最大字符数，包含换行符（最小值是1，最大值是32767）。如果没有指定，会指定一个默认值1024。

• DBE_FILE.WRITE_NCHAR

  函数DBE_FILE.WRITE_NCHAR用于向文件中写入buffer中的数据，文件必须以国家字符集模式和写模式打开，这个操作不会写入行终结符，返回值永远为TRUE。文本字符串将以UTF8字符集格式写入。

  DBE_FILE.WRITE_NCHAR函数原型为：

  1 2 3 4

  DBE_FILE.WRITE_NCHAR( file IN DBE_FILE.FILE_TYPE, buffer IN NVARCHAR2) RETURN VOID;

  表23 DBE_FILE.WRITE接口参数说明

  参数	描述
  file	通过FOPEN_NCHAR打开的DBE_FILE.FILE_TYPE类型的对象，要写入的文件必须以写模式打开，这个操作不会写入行终结符。
  buffer	写入文件的文本数据。每行的累计写入长度不能大于或等于FOPEN_NCHAR时指定或默认的max_line_size，否则会在刷新到文件时报错。 说明： 对于写操作，会检测写入文件类型，如果为elf类型文件，会报错退出。

• DBE_FILE.WRITE_LINE_NCHAR

  函数DBE_FILE.WRITE_LINE_NCHAR用于向文件中写入buffer中的数据，文件必须以国家字符集模式和写模式打开，这个操作会自动追加行终结符，返回值永远为TRUE。文本字符串将以UTF8字符集格式写入。

  DBE_FILE.WRITE_LINE_NCHAR函数原型为：

  1 2 3 4

  DBE_FILE.WRITE_LINE_NCHAR( file IN DBE_FILE.FILE_TYPE, buffer IN NVARCHAR2) RETURN VOID;

  表24 DBE_FILE.WRITE_LINE接口参数说明

  参数	描述
  file	通过FOPEN_NCHAR打开的DBE_FILE.FILE_TYPE类型的对象。
  buffer	要写入文件的文本数据，每行的长度（包含换行符）不能大于FOPEN_NCHAR时指定或默认的max_line_size，否则会在刷新到文件时报错。 说明： 对于写操作，会检测写入文件类型，如果为elf类型文件，会报错退出。

• DBE_FILE.FORMAT_WRITE_NCHAR

  函数DBE_FILE.FORMAT_WRITE_NCHAR将格式化数据写入到一个打开的文件，是允许格式化的DBE_FILE.WRITE_NCHAR接口，返回值永远为TRUE。

  DBE_FILE.FORMAT_WRITE_NCHAR函数原型为：

  1 2 3 4 5 6 7

  DBE_FILE.FORMAT_WRITE_NCHAR( file IN DBE_FILE.FILE_TYPE, format IN NVARCHAR2, arg1 IN NVARCHAR2 DEFAULT NULL, . . . arg5 IN NVARCHAR2 DEFAULT NULL) RETURN VOID;

  表25 DBE_FILE.FORMAT_WRITE_NCHAR接口参数说明

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

• DBE_FILE.READ_LINE_NCHAR

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

  DBE_FILE.READ_LINE_NCHAR存储过程原型为：

  1 2 3 4

  DBE_FILE.READ_LINE_NCHAR( file IN DBE_FILE.FILE_TYPE, buffer OUT NVARCHAR2, len IN INTEGER DEFAULT NULL);

  表26 DBE_FILE.READ_LINE接口参数说明

  参数	描述
  file	通过FOPEN_NCHAR打开的DBE_FILE.FILE_TYPE类型的对象，文件必须以读模式打开，否则会抛出INVALID_OPERATION的异常。
  buffer	接收数据的buffer。
  len	从文件中读取的字节数，默认值为NULL。如果是NULL，会使用max_line_size来指定大小。