Oracle Built−in Packages- P71 ppsx

Programs in UTL_FILE may also raise the following standard system exceptions: NO_DATA_FOUND Raised when you read past the end of the file with UTL_FILE.GET_LINE.. 6.2.1.6 UTL_FILE nonpro

The value you provided for the open_mode parameter in UTL_FILE.FOPEN was invalid It must be

"A," "R," or "W."

INVALID_FILEHANDLE

The file handle you passed to a UTL_FILE program was invalid You must call UTL_FILE.FOPEN

to obtain a valid file handle

INVALID_OPERATION

UTL_FILE could not open or operate on the file as requested For example, if you try to write to a read−only file, you will raise this exception

READ_ERROR

The operating system returned an error when you tried to read from the file (This does not occur very often.)

WRITE_ERROR

The operating system returned an error when you tried to write to the file (This does not occur very often.)

INTERNAL_ERROR

Uh−oh Something went wrong and the PL/SQL runtime engine couldn't assign blame to any of the previous exceptions Better call Oracle Support!

Programs in UTL_FILE may also raise the following standard system exceptions:

NO_DATA_FOUND

Raised when you read past the end of the file with UTL_FILE.GET_LINE

VALUE_ERROR

Raised when you try to read or write lines in the file which are too long The current implementation

of UTL_FILE limits the size of a line read by UTL_FILE.GET_LINE to 1022 bytes

INVALID_MAXLINESIZE

Oracle 8.0 and above: raised when you try to open a file with a maximum linesize outside of the valid range (between 1 through 32767)

In the following descriptions of the UTL_FILE programs, I list the exceptions that can be raised by each individual program

6.2.1.6 UTL_FILE nonprogram elements

When you open a file, PL/SQL returns a handle to that file for use within your program This handle has a datatype of UTL_FILE.FILE_TYPE currently defined as the following:

TYPE UTL_FILE.FILE_TYPE IS RECORD (id BINARY_INTEGER);

As you can see, UTL_FILE.FILE_TYPE is actually a PL/SQL record whose fields contain all the information about the file needed by UTL_FILE However, this information is for use only by the UTL_FILE package You will reference the handle, but not any of the individual fields of the handle (The fields of this record may expand over time as UTL_FILE becomes more sophisticated.)

Here is an example of how to declare a local file handle based on this type:

DECLARE

file_handle UTL_FILE.FILE_TYPE;

.

6.2.1.7 UTL_FILE restrictions and limitations

While UTL_FILE certainly extends the usefulness of PL/SQL, it does have its drawbacks, including:

•

Prior to Oracle 8.0, you cannot read or write a line of text with more than 1023 bytes In Oracle 8.0 and above, you can specify a maximum line size of up to 32767 when you open a file

•

You cannot delete files through UTL_FILE The best you can do is empty a file, but it will still be

present on the disk

•

You cannot rename files The best you can do is copy the contents of the file to another file with that new name

•

You do not have random access to lines in a file If you want to read the 55th line, you must read through the first 54 lines If you want to insert a line of text between the 1,267th and 1,268th lines, you will have to (a) read those 1,267 lines, (b) write them to a new file, (c) write the inserted line of text, and (d) read/write the remainder of the file Ugh

•

You cannot change the security on files through UTL_FILE

•

You cannot access mapped files Generally, you will need to supply real directory locations for files if you want to read from or write to them

You are probably getting the idea UTL_FILE is a basic facility for reading and writing server−side files Working with UTL_FILE is not always pretty, but you can usually get what you need done with a little or a lot of code

6.2.1.8 The UTL_FILE process flow

The following sections describe each of the UTL_FILE programs, following the process flow for working with files That flow is described for both writing and reading files

In order to write to a file you will (in most cases) perform the following steps:

1

Declare a file handle This handle serves as a pointer to the file for subsequent calls to programs in the UTL_FILE package to manipulate the contents of this file

2

Open the file with a call to FOPEN, which returns a file handle to the file You can open a file to read, replace, or append text

3

Write data to the file using the PUT, PUTF, or PUT_LINE procedures

4

Close the file with a call to FCLOSE This releases resources associated with the file.

To read data from a file you will (in most cases) perform the following steps:

1

Declare a file handle

2

Declare a VARCHAR2 string buffer that will receive the line of data from the file You can also read directly from a file into a numeric or date buffer In this case, the data in the file will be converted implicitly, and so it must be compatible with the datatype of the buffer

3

Open the file using FOPEN in read mode

4

Use the GET_LINE procedure to read data from the file and into the buffer To read all the lines from

a file, you would execute GET_LINE in a loop

5

Close the file with a call to FCLOSE

6.2.2 Opening Files

Use the FOPEN and IS_OPEN functions when you open files via UTL_FILE

NOTE: Using the UTL−FILE package, you can only open a maximum of ten files for each

Oracle session

6.2.2.1 The UTL_FILE.FOPEN function

The FOPEN function opens the specified file and returns a file handle that you can then use to manipulate the file Here's the header for the function:

All PL/SQL versions: Oracle 8.0 and above only:

FUNCTION UTL_FILE.FOPEN ( FUNCTION UTL_FILE.FOPEN (

location IN VARCHAR2, location IN VARCHAR2,

filename IN VARCHAR2, filename IN VARCHAR2,

open_mode IN VARCHAR2) open_mode IN VARCHAR2,

RETURN file_type; max_linesize IN BINARY_INTEGER)

RETURN file_type;

Parameters are summarized in the following table

Parameter Description

location Location of the file

filename Name of the file

openmode Mode in which the file is to be opened (see the following modes)

max_linesize The maximum number of characters per line, including the newline character, for this file

Minimum is 1, maximum is 32767 You can open the file in one of three modes:

R

Open the file read−only If you use this mode, use UTL_FILE's GET_LINE procedure to read from the file

W

Open the file to read and write in replace mode When you open in replace mode, all existing lines in the file are removed If you use this mode, then you can use any of the following UTL_FILE

programs to modify the file: PUT, PUT_LINE, NEW_LINE, PUTF, and FFLUSH

A

Open the file to read and write in append mode When you open in append mode, all existing lines in the file are kept intact New lines will be appended after the last line in the file If you use this mode, then you can use any of the following UTL_FILE programs to modify the file: PUT, PUT_LINE, NEW_LINE, PUTF, and fFFLUSH

Keep the following points in mind as you attempt to open files:

•

The file location and the filename joined together must represent a legal filename on your operating system

•

The file location specified must be accessible and must already exist; FOPEN will not create a

directory or subdirectory for you in order to write a new file, for example

•

If you want to open a file for read access, the file must already exist If you want to open a file for write access, the file will either be created, if it does not exist, or emptied of all its contents, if it does exist

•

If you try to open with append, the file must already exist UTL_FILE will not treat your append request like a write access request If the file is not present, UTL_FILE will raise the

INVALID_OPERATION exception

6.2.2.1.1 Exceptions

FOPEN may raise any of the following exceptions, described earlier:

UTL_FILE.INVALID_MODE

UTL_FILE.INVALID_OPERATION

UTL_FILE.INVALID_PATH

UTL_FILE.INVALID_MAXLINESIZE

6.2.2.1.2 Example

The following example shows how to declare a file handle and then open a configuration file for that handle

in read−only mode:

DECLARE

config_file UTL_FILE.FILE_TYPE;

BEGIN

config_file := UTL_FILE.FOPEN ('/maint/admin', 'config.txt', 'R');

6.2.2.2 The UTL_FILE.IS_OPEN function

The IS_OPEN function returns TRUE if the specified handle points to a file that is already open Otherwise, it returns false The header for the function is:

FUNCTION UTL_FILE.IS_OPEN (file IN UTL_FILE.FILE_TYPE) RETURN BOOLEAN;

where file is the file to be checked

Within the context of UTL_FILE, it is important to know what this means The IS_OPEN function does not perform any operating system checks on the status of the file In actuality, it merely checks to see if the id field of the file handle record is not NULL If you don't play around with these records and their contents, then this id field is only set to a non−NULL value when you call FOPEN It is set back to NULL when you call FCLOSE

6.2.3 Reading from Files

UTL_FILE provides only one program to retrieve data from a file: the GET_LINE procedure

6.2.3.1 The UTL_FILE.GET_LINE procedure

The GET_LINE procedure reads a line of data from the specified file, if it is open, into the provided line buffer Here's the header for the procedure:

PROCEDURE UTL_FILE.GET_LINE

(file IN UTL_FILE.FILE_TYPE,

buffer OUT VARCHAR2);

Parameters are summarized in the following table

Parameter Description

file The file handle returned by a call to FOPEN

buffer The buffer into which the line of data is read

The variable specified for the buffer parameter must be large enough to hold all the data up to the next

carriage return or end−of−file condition in the file If not, PL/SQL will raise the VALUE_ERROR exception The line terminator character is not included in the string passed into the buffer

6.2.3.1.1 Exceptions

GET_LINE may raise any of the following exceptions:

NO_DATA_FOUND

VALUE_ERROR

UTL_FILE.INVALID_FILEHANDLE

UTL_FILE.INVALID_OPERATION

UTL_FILE.READ_ERROR

6.2.3.1.2 Example

Since GET_LINE reads data only into a string variable, you will have to perform your own conversions to local variables of the appropriate datatype if your file holds numbers or dates Of course, you could call this procedure and read data directly into string and numeric variables as well In this case, PL/SQL will be

performing a runtime, implicit conversion for you In many situations, this is fine I generally recommend that you avoid implicit conversions and perform your own conversion instead This approach more clearly

documents the steps and dependencies Here is an example: