Oracle8 Server Unleashed:Supplied PL/SQL Packages

Table of Contents

`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

Table of Contents