| Previous | Table of Contents | Next |
| location | The directory path where the file either exists or is to be created. This value must be quoted (forexample, '/u01/app/oracle’). |
| filename | The name of the file. If open_mode is ‘w’, an existing file of the same name will be overwritten. |
| open_mode | The mode to open the file in: ,TT>‘r’ opens the file for reading text. ‘w’ creates the file and keeps it open for writing. ‘a’ creates or opens the file for appending text. |
| return value | The file handle used to identify the file in later procedure calls. |
Exceptions:
UTL_FILE.INVALID_PATH UTL_FILE.INVALID_MODE UTL_FILE.INVALID_OPERATION UTL_FILE.INTERNAL_ERROR
Note:
UTL_FILE.INTERNAL_ERROR may be raised for any UTL_FILE procedure or function.
FOPEN is the first operation that must be performed when reading from or writing to a file. A file that is opened in write mode cannot be read from, and vice-versa. The file must first be closed and then reopened in the new mode.
PROCEDURE FCLOSE(
file_handle IN FILE_TYPE);
| file_handle | File handle returned fromFOPEN. |
Exceptions:
UTL_FILE.WITE_ERROR UTL_FILE.INVALID_FILEHANDLE
Caution:
All files that are opened should also be closed to ensure that pending changes are written from the buffer into the file.
PROCEDURE FCLOSE_ALL;
Exceptions:
UTL_FILE.WRITE_ERROR
This procedure applies all pending changes and closes all opened files. It requires no parameters and has no return value. FCLOSE_ALL is usually used for cleanup.
FUNCTION IS_OPEN(
file_handle IN FILE_TYPE)
RETURN BOOLEAN;
This function returns a TRUE if the file is open and a FALSE if it is not. No exceptions can be raised except possibly UTL_FILE.INTERNAL_ERROR.
PROCEDURE PUT(file_handle IN FILE_TYPE,
buffer IN VARCHAR2);
| file_handle | File handle returned by FOPEN. |
| buffer | String to be written to file. |
Exceptions:
UTL_FILE.INVALID_FILEHANDLE UTL_FILE.INVALID_OPERATION UTL_FILE.WRITE_ERROR
A string can be written to a file opened in the ‘w’ or ‘a’ mode using this procedure. It appends the string to an existing line and will not create a new line character. Use NEW_LINE or PUT_LINE to create a line terminator.
PROCEDURE NEW_LINE(
file_handle IN FILE_TYPE,
lines IN NATURAL := 1);
| file_handle | File handle returned by FOPEN. |
| lines | Number of line terminators to create. Default is 1. |
Exceptions:
UTL_FILE.INVALID_FILEHANDLE UTL_FILE.INVALID_OPERATION
This procedure inserts the number of line terminators specified by lines. The operating system determines the type of termination character to use.
PROCEDURE PUT_LINE(
file_handle IN FILE_TYPE,
buffer IN VARCHAR2);
This procedure is identical to PUT, except that it appends a single-line terminator after the specified input string.
PROCEDURE PUTF(
file_handle IN FILE_TYPE,
format IN VARCHAR2,
arg1 IN VARCHAR2 default NULL,
arg2 IN VARCHAR2 default NULL,
arg3 IN VARCHAR2 default NULL,
arg4 IN VARCHAR2 default NULL,
arg5 IN VARCHAR2 default NULL);
| file_handle | File handle returned by FOPEN. |
| format | String and special characters /n and %s. |
| arg1—5 | Substitutions for %s in the format value. |
Exceptions:
UTL_FILE.WRITE_ERROR UTL_FILE.INVALID_OPERATION
This procedure allows a formatted string to be inserted into the file in the same manner as the C function printf(). Up to five substitutions using %s can be performed. Substitution strings are provided at the end of the format string as arg1 through 5. A substitution string without a corresponding argument is replaced with a NULL. /n is interpreted as a new line character.
PROCEDURE FFLUSH(
file_handle IN FILE_TYPE);
Exceptions:
UTL_FILE.INVALID_HANDLE UTL_FILE.INVALID_OPERATION UTL_FILE.WRITE_ERROR
Use FFLUSH to flush the output buffer and write it to the file. Normally, all writes are buffered until the buffer reaches max capacity. Only FCLOSE, FCLOSE_ALL, or FFLUSH will flush this buffer if it is not full.
PROCEDURE GET_LINE(
file_handle IN FILE_TYPE,
buffer OUT VARCHAR2);
Exceptions:
UTL_FILE.INVALID_FILEHANDLE UTL_FILE.INVALID_OPERATION UTL_FILE.NO_DATA_FOUND UTL_FILE.READ_ERROR UTL_FILE.VALUE_ERROR
| Previous | Table of Contents | Next |