Using the Oracle UTL_FILE Package

The Oracle Server has many PL/SQL system-supplied packages to extend database
functionality and provide PL/SQL access to SQL features. The package DBMS_OUTPUT
generates output to the screen useful while debugging code while the package UTL_FILE
writes output to external files. This article discusses the UTL_FILE package.

Using the UTL_FILE package, PL/SQL programs can read from and write to operating
system text files. For example, suppose that we wanted to create a sales report and write this
report to a text file with a comma-separated values (CSV) format. To accomplish this task,
within the PL/SQL program, we would use a combination of query operations and calls to the
UTL_FILE package.

Before we look at the PL/SQL program described above, however, we need to consider an
auxiliary topic: the directory object. When interacting with external objects, a database does
so by means of a directory object. Essentially, a directory object is a database object that
maps to an OS directory. Once created, the directory object may be used by database features
(e.g., the UTL_FILE) to access external objects.

Creating a directory object is rather straightforward: we use the CREATE DIRECTORY

command, e.g.,

CREATE DIRECTORY OutputDirectory AS 'C:\Test';

After executing this command, the OS directory ‘C:\Test’ is now available to database
programs under the name OutputDirectory.

Proceeding now to our primary task of creating a Sales Report to be written to an external file,
we examine the following code:

1 CREATE OR REPLACE PROCEDURE SalesReport (StartOrderDate DATE,

2 EndOrderDate DATE)
3 AS
4 CURSOR c1 IS
5 SELECT e.FirstName, e.LastName, COUNT(o.OrderID),
6 SUM(od.UnitPrice * od.Quantity * (1-Discount))
7 FROM Employees e JOIN Orders o ON (e.EmployeeID = o.EmployeeID)
8 JOIN order_details od ON (o.OrderID = od.OrderID)
9 WHERE o.OrderDate BETWEEN StartOrderDate AND EndOrderDate
10 GROUP BY e.FirstName, e.LastName
11 ORDER BY e.LastName, e.FirstName;
12
13 fname employees.firstname%TYPE;
14 lname employees.lastname%TYPE;
15 ordersCount NUMBER;
16 rev NUMBER;
17
18 OutputRecord VARCHAR2(255);
19 OutputFile utl_file.FILE_TYPE;
20
21 BEGIN
22
23 OPEN c1;
24
25 FETCH c1 INTO fname, lname, orderscount, rev;
26
27 OutputFile := utl_file.fopen(UPPER('OutputDirectory'),
28 'SalesReport.csv', 'w', 32767);
29
30 WHILE c1%FOUND LOOP
31 OutputRecord := fname || ',' || lname || ',' || orderscount || ','
32 || rev;
33 utl_file.put (OutputFile, OutputRecord);
34 utl_file.new_line (OutputFile);
35 FETCH c1 INTO fname, lname, orderscount, rev;
36 END LOOP;
37
38 CLOSE c1;
utl_file.fclose(OutputFile);

END;

The program above contains the standard PL/SQL structures (explicit cursor and loop) to
fetch the desired data. We explain the calls to the UTL_FILE procedures as follows:

 Lines 26 and 36: The FOPEN() and FCLOSE() procedures respectively, are called
to create and close the desired text file.
 The FOPEN() procedure accepts as parameters the name of the directory object
(OutputDirectory), the file name of the external file that will be generated
(‘SalesReport.csv’), the access mode (‘w’ for write) and the maximum size in bytes
for each line (32767).
 Line 18: The FOPEN() procedure returns a special type named FILE_TYPE defined
in the UTL_FILE package. Thus, any identifier that will receive the value returned by
FOPEN() has to be of this special type.
 Line 29: As each cursor record is processed within the loop, this record is formatted
as a comma-separated record that is to be written to the text file.
 Lines 30 and 31: The PUT() procedure writes the line of text to the external file while
the NEW_LINE() procedure writes a line terminator to the file.

The CSV file generated by this program may then be imported to other environments.