FOPEN Function

This function opens a file for input or output. The file location must be an accessible directory, as defined in the instance's initialization parameter UTL_FILE_DIR. The complete directory path must already exist; it is not created by FOPEN.

FOPEN returns a file handle, which must be used in all subsequent I/O operations on the file.

This version of FOPEN does not take a parameter for the maximum line size. Thus, the default (which is 1023 on most systems) is used. To specify a different maximum line size, use the other, overloaded version of "FOPEN Function".

You can have a maximum of 50 files open simultaneously. See also "FOPEN_NCHAR Function".

Syntax

UTL_FILE.FOPEN (
   location  IN VARCHAR2,
   filename  IN VARCHAR2,
   open_mode IN VARCHAR2)
  RETURN UTL_FILE.FILE_TYPE;

Parameters

Table 77-3 FOPEN Function Parameters

Parameters	Description
location	Operating system-specific string that specifies the directory in which to open the file.
filename	Name of the file, including extension (file type), without any directory path information. (Under the UNIX operating system, the filename cannot be terminated with a /).
open_mode	String that specifies how the file should be opened (either upper or lower case letters can be used). The supported values, and the UTL_FILE procedures that can be used with them are: r read text (GET_LINE) w write text (PUT, PUT_LINE, NEW_LINE, PUTF, FFLUSH) a append text (PUT, PUT_LINE, NEW_LINE, PUTF, FFLUSH)

Note: If you open a file that does not exist using the a value for open_mode, then the file is created in write (w) mode.

Returns

FOPEN returns a file handle, which must be passed to all subsequent procedures that operate on that file. The specific contents of the file handle are private to the UTL_FILE package, and individual components should not be referenced or changed by the UTL_FILE user.

Note: The file location and file name parameters are supplied to the FOPEN function as separate strings, so that the file location can be checked against the list of accessible directories as specified in the initialization file. Together, the file location and name must represent a legal filename on the system, and the directory must be accessible. A subdirectory of an accessible directory is not necessarily also accessible; it too must be specified using a complete path name in the initialization file. Operating system-specific parameters, such as C-shell environment variables under UNIX, cannot be used in the file location or file name parameters.

Exceptions

INVALID_PATH
INVALID_MODE
INVALID_OPERATION