
# DBE_FILE
DBE_FILE包为存储过程提供了读、写操作系统文本文件的能力。
#### 接口介绍
高级功能包DBE_FILE支持的所有接口请参见[表1]。
 表1DBE_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函数原型为：
  ```
  DBE_FILE.OPEN (
  dir             IN    VARCHAR2,
  file_name       IN    VARCHAR2,
  open_mode       IN    VARCHAR2,
  max_line_size   IN    INTEGER DEFAULT 1024)
  RETURN INTEGER;
  ```
  表2DBE_FILE.OPEN接口参数说明 
  | 参数            | 类型       | 入参/出参 | 是否可以为空 | 描述                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
  |:---|:---|:---|:---|:---|
  | dir           | VARCHAR2 | IN    | 否      | 文件的目录位置，这个字符串是一个目录对象名。 说明： - 文件目录的位置，需要添加到系统表[PG_DIRECTORY](https://support.huaweicloud.com/centralized-devg-v2-gaussdb/gaussdb_42_0664.html#ZH-CN_TOPIC_0000002186016490)中，如果传入的路径和[PG_DIRECTORY](https://support.huaweicloud.com/centralized-devg-v2-gaussdb/gaussdb_42_0664.html#ZH-CN_TOPIC_0000002186016490)中的路径不匹配，会报路径不存在的错误，下面的涉及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_CLOSE
  函数DBE_FILE.IS_CLOSE用于检测一个文件句柄是否已经关闭，返回布尔值，异常情况是INVALID_FILEHANDLE。
  DBE_FILE.IS_CLOSE函数原型为：
  ```
  DBE_FILE.IS_CLOSE (
  file      IN     INTEGER)
  RETURN BOOLEAN;
  ```
  表3DBE_FILE.IS_CLOSE接口参数说明 
  | 参数              | 类型      | 入参/出参 | 是否可以为空 | 描述            |
  |:---|:---|:---|:---|:---|
  | file IN INTEGER | INTEGER | IN    | 是      | 传入一个要检测的文件句柄。 |
     
  
- DBE_FILE.READ_LINE
  存储过程DBE_FILE.READ_LINE从一个打开的文件读取数据，并把读取的结果存放到BUFFER中。读取的时候会读取到行尾，但不包含行终结符，或者读取到文件末尾，或者读取到len参数指定的大小。读取的长度不能超过OPEN的时候指定的max_line_size。
  DBE_FILE.READ_LINE函数原型为：
  ```
  DBE_FILE.READ_LINE (
  file      IN   INTEGER,
  buffer    OUT  VARCHAR2,
  len       IN   INTEGER DEFAULT NULL)
  ```
  表4DBE_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函数原型为：
  ```
  DBE_FILE.WRITE (
  file     IN     INTEGER,
  buffer   IN     TEXT)
  RETURN BOOLEAN;;
  ```
  表5DBE_FILE.WRITE接口参数说明 
  | 参数     | 类型      | 入参/出参 | 是否可以为空 | 描述                                                                                                                                                                                                                                                                                                   |
  |:---|:---|:---|:---|:---|
  | file   | INTEGER | IN    | 否      | 该存储过程用于向文件中写入BUFFER中的数据，要写入的文件必须以写模式打开，这个操作不会写入行终结符。                                                                                                                                                                                                                                                 |
  | buffer | TEXT    | IN    | 是      | 要写入文件的文本数据，BUFFER的最大值是32767个字节。如果在open的时候没有指定值，默认是1024个字节，没有刷新到文件之前，一系列的WRITE操作的BUFFER总和不能超过32767个字节。 说明： 对于写操作，会检测写入文件类型，如果为elf类型文件，会报错退出。 |
     
  
- DBE_FILE.NEW_LINE
  函数DBE_FILE.NEW_LINE用于向文件对应的缓冲区中写入一个或者多个行终结符，行终结符和平台相关。
  DBE_FILE.NEW_LINE函数原型为：
  ```
  DBE_FILE.NEW_LINE (
  file         IN     INTEGER,
  line_nums    IN     INTEGER := 1)
  RETURN BOOLEAN;
  ```
  表6DBE_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函数原型为：
  ```
  DBE_FILE.WRITE_LINE(
  file       IN     INTEGER,
  buffer     IN     TEXT,
  flush      IN     BOOLEAN DEFAULT FALSE)
  RETURN BOOLEAN;
  ```
  表7DBE_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函数原型为：
  ```
  DBE_FILE.FORMAT_WRITE (
  file   IN INTEGER,
  format IN VARCHAR2,
  arg1  IN VARCHAR2 DEFAULT NULL,
  . . .
  arg6 IN VARCHAR2 DEFAULT NULL])
  RETURN BOOLEAN;
  ```
  表8DBE_FILE.FORMAT_WRITE接口参数说明 
  | 参数                | 类型       | 入参/出参 | 是否可以为空 | 描述                                                         |
  |:---|:---|:---|:---|:---|
  | file              | INTEGER  | IN    | 否      | 通过OPEN打开的文件句柄。                                             |
  | format            | VARCHAR2 | IN    | 是      | 一个要进行格式化的字符串包含，文本和格式符\\n和%s。                               |
  | \[arg1. . .arg6\] | VARCHAR2 | IN    | 是      | 从1到6个可选的参数串，参数和格式化字符的位置是一一对应的，如果存在格式化字符而没有提供参数，会使用空串来替代%s。 |
     
  
- DBE_FILE.GET_RAW
  存储过程DBE_FILE.GET_RAW从一个打开的文件读取RAW类型数据，并把读取的结果存放到BUFFER中，从r中返回。
  DBE_FILE.GET_RAW函数原型为：
  ```
  DBE_FILE.GET_RAW (
  file    IN   INTEGER,
  r       OUT  RAW,
  length  IN   INTEGER DEFAULT NULL);
  ```
  表9DBE_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函数原型为：
  ```
  DBE_FILE.PUT_RAW (
  file    IN  INTEGER,
  r       IN  RAW,
  flush   IN  BOOLEAN DEFAULT FALSE)
  RETURN BOOLEAN;
  ```
  表10DBE_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函数原型为：
  ```
  DBE_FILE.FLUSH (
  file     IN     INTEGER)
  RETURN VOID;
  ```
  表11DBE_FILE.FLUSH接口参数说明 
  | 参数   | 类型      | 入参/出参 | 是否可以为空 | 描述             |
  |:---|:---|:---|:---|:---|
  | file | INTEGER | IN    | 否      | 通过OPEN打开的文件句柄。 |
     
  
- DBE_FILE.CLOSE
  函数DBE_FILE.CLOSE用于关闭一个打开的文件句柄，当调用这个函数的时候，如果还有等待写入的缓存的数据，可能会收到异常信息。
  DBE_FILE.CLOSE函数原型为：
  ```
  DBE_FILE.CLOSE (
  file IN INTEGER
  )RETURN INTEGER;
  ```
  表12DBE_FILE.CLOSE接口参数说明 
  | 参数   | 类型      | 入参/出参 | 是否可以为空 | 描述             |
  |:---|:---|:---|:---|:---|
  | file | INTEGER | IN    | 否      | 通过OPEN打开的文件句柄。 |
     
  
- DBE_FILE.CLOSE_ALL
  函数DBE_FILE.CLOSE_ALL关闭一个会话中打开的所有的文件句柄，可用于紧急的清理操作。
  DBE_FILE.CLOSE_ALL函数原型为：
  ```
  DBE_FILE.CLOSE_ALL()
  RETRUN VOID;
  ```
  表13DBE_FILE.CLOSE_ALL接口参数说明 
  | 参数 | 描述 |
  |:---|:---|
  | 无  | 无  |
     
  
- DBE_FILE.REMOVE
  函数DBE_FILE.REMOVE删除一个磁盘文件，使用的时候需要有充分的权限。
  DBE_FILE.REMOVE函数原型为：
  ```
  DBE_FILE.REMOVE (
  dir           IN     VARCHAR2,
  file_name     IN     VARCHAR2)
  RETURN VOID;
  ```
  表14DBE_FILE.REMOVE接口参数说明 
  | 参数        | 类型       | 入参/出参 | 是否可以为空 | 描述                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
  |:---|:---|:---|:---|:---|
  | dir       | VARCHAR2 | IN    | 否      | 文件的目录位置，这个字符串是一个目录对象名。 说明： - 文件目录的位置，需要添加到系统表[PG_DIRECTORY](https://support.huaweicloud.com/centralized-devg-v2-gaussdb/gaussdb_42_0664.html#ZH-CN_TOPIC_0000002186016490)中，如果传入的路径和[PG_DIRECTORY](https://support.huaweicloud.com/centralized-devg-v2-gaussdb/gaussdb_42_0664.html#ZH-CN_TOPIC_0000002186016490)中的路径不匹配，会报路径不存在的错误，下面的涉及location作为参数的函数也是同样的情况。  - 在打开guc参数safe_data_path时，用户只能通过高级包读写safe_data_path指定文件路径下的文件。   |
  | file_name | VARCHAR2 | IN    | 否      | 文件名。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
     
  
- DBE_FILE.RENAME
  函数DBE_FILE.RENAME重命名一个磁盘文件，类似Unix的mv指令。
  DBE_FILE.RENAME函数原型为：
  ```
  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;
  ```
  表15DBE_FILE.RENAME接口参数说明 
  | 参数             | 类型       | 入参/出参 | 是否可以为空 | 描述                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
  |:---|:---|:---|:---|:---|
  | src_dir        | VARCHAR2 | IN    | 否      | 源文件的目录位置（大小写敏感）。 说明： - 文件目录的位置，需要添加到系统表[PG_DIRECTORY](https://support.huaweicloud.com/centralized-devg-v2-gaussdb/gaussdb_42_0664.html#ZH-CN_TOPIC_0000002186016490)中，如果传入的路径和[PG_DIRECTORY](https://support.huaweicloud.com/centralized-devg-v2-gaussdb/gaussdb_42_0664.html#ZH-CN_TOPIC_0000002186016490)中的路径不匹配，会报路径不存在的错误，下面的涉及location作为参数的函数也是同样的情况。  - 在打开guc参数safe_data_path时，用户只能通过高级包读写safe_data_path指定文件路径下的文件。    |
  | src_file_name  | VARCHAR2 | IN    | 否      | 要进行命名的源文件。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
  | dest_dir       | VARCHAR2 | IN    | 否      | 目的目录位置（大小写敏感）。 说明： - 文件目录的位置，需要添加到系统表[PG_DIRECTORY](https://support.huaweicloud.com/centralized-devg-v2-gaussdb/gaussdb_42_0664.html#ZH-CN_TOPIC_0000002186016490)中，如果传入的路径和[PG_DIRECTORY](https://support.huaweicloud.com/centralized-devg-v2-gaussdb/gaussdb_42_0664.html#ZH-CN_TOPIC_0000002186016490)中的路径不匹配，会报路径不存在的错误，下面的涉及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函数原型为：
  ```
  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;
  ```
  表16DBE_FILE.COPY接口参数说明 
  | 参数             | 类型       | 入参/出参 | 是否可以为空 | 描述                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
  |:---|:---|:---|:---|:---|
  | src_dir        | VARCHAR2 | IN    | 否      | 源文件所在的目录。 说明： - 文件目录的位置，需要添加到系统表[PG_DIRECTORY](https://support.huaweicloud.com/centralized-devg-v2-gaussdb/gaussdb_42_0664.html#ZH-CN_TOPIC_0000002186016490)中，如果传入的路径和[PG_DIRECTORY](https://support.huaweicloud.com/centralized-devg-v2-gaussdb/gaussdb_42_0664.html#ZH-CN_TOPIC_0000002186016490)中的路径不匹配，会报路径不存在的错误，下面的涉及location作为参数的函数也是同样的情况。  - 在打开guc参数safe_data_path时，用户只能通过高级包读写safe_data_path指定文件路径下的文件。   |
  | src_file_name  | VARCHAR2 | IN    | 否      | 要拷贝的源文件。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
  | dest_dir       | VARCHAR2 | IN    | 否      | 目的文件所在的目录。 说明： - 文件目录的位置，需要添加到系统表[PG_DIRECTORY](https://support.huaweicloud.com/centralized-devg-v2-gaussdb/gaussdb_42_0664.html#ZH-CN_TOPIC_0000002186016490)中，如果传入的路径和[PG_DIRECTORY](https://support.huaweicloud.com/centralized-devg-v2-gaussdb/gaussdb_42_0664.html#ZH-CN_TOPIC_0000002186016490)中的路径不匹配，会报路径不存在的错误，下面的涉及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存储过程原型为：
  ```
  DBE_FILE.GET_ATTR(
  location IN text,
  filename IN text,
  OUT fexists boolean,
  OUT file_length bigint,
  OUT block_size integer);
  ```
  表17DBE_FILE.GET_ATTR接口参数说明 
  | 参数          | 类型      | 入参/出参 | 是否可以为空 | 描述                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
  |:---|:---|:---|:---|:---|
  | location    | TEXT    | IN    | 否      | 文件所在的目录。 说明： - 文件目录的位置，需要添加到系统表[PG_DIRECTORY](https://support.huaweicloud.com/centralized-devg-v2-gaussdb/gaussdb_42_0664.html#ZH-CN_TOPIC_0000002186016490)中，如果传入的路径和[PG_DIRECTORY](https://support.huaweicloud.com/centralized-devg-v2-gaussdb/gaussdb_42_0664.html#ZH-CN_TOPIC_0000002186016490)中的路径不匹配，会报路径不存在的错误，下面的涉及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函数原型为：
  ```
  DBE_FILE.SEEK (
  file            IN INTEGER,
  absolute_start  IN     BIGINT DEFAULT NULL,
  relative_start  IN     BIGINT DEFAULT NULL)
  RETURN VOID;
  ```
  表18DBE_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函数原型为：
  ```
  DBE_FILE.GET_POS (
  file    IN     INTEGER)
  RETURN BIGINT;
  ```
  表19DBE_FILE.GET_POS接口参数说明 
  | 参数   | 类型      | 入参/出参 | 是否可以为空 | 描述             |
  |:---|:---|:---|:---|:---|
  | file | INTEGER | IN    | 否      | 通过OPEN打开的文件句柄。 |
     
  
- DBE_FILE.IS_OPEN
  函数DBE_FILE.GET_POS以字节为单位返回文件当前的偏移量。
  DBE_FILE.IS_OPEN函数原型为：
  ```
  DBE_FILE.IS_OPEN (
  file      IN     INTEGER)
  RETURN BOOLEAN;
  ```
  表20DBE_FILE.IS_OPEN接口参数说明 
  | 参数   | 类型      | 入参/出参 | 是否可以为空 | 描述             |
  |:---|:---|:---|:---|:---|
  | file | INTEGER | IN    | 否      | 通过OPEN打开的文件句柄。 |
     
  
 
#### 示例
```
--系统管理员向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
```
