UTL File package

Here are simple examples to understand the UTL_FILE enhancement in Oracle 9i Release 2
Examples discussed in this article are

COPYING OS FILE ON DIFFERENT LOCATION

COPYING OS FILE ON NETWORK LOCATION
RENAME OS FILE
GETTING ATTRIBUTE OF A OS FILE

To understand, make the following setup, which is on WIN2K machine.

You can make the similar set for Unix.

Create a director LOC1 and LOC2 under C:\TEMP

U:\>sqlplus /nolog
SQL*Plus: Release 9.2.0.1.0 - Production on Wed Feb 19 16:40:39 2003
Copyright (c) 1982, 2002, Oracle Corporation. All rights reserved.

SQL> connect sys as sysdba

Enter password:
Connected.

SQL> show parameter utl

NAME TYPE VALUE

------------------------------------ ----------- ---------------------
utl_file_dir string

Now tell oracle about your directories as follows (Connect as sys)

create or replace directory dbdir as 'C:\TEMP\LOC1\';

Grant read on directory dbdir to Scott;
Create or replace directory DBDIR2 as 'C:\TEMP\LOC2\';
Grant read on directory DBDIR2 to Scott;

SQL> select * from dba_directories;

OWNER DIRECTORY_NAME DIRECTORY_PATH

---------- --------------- ---------------------------------
SYS DBDIR C:\TEMP\LOC1\
SYS DBDIR2 C:\TEMP\LOC2\

For sample test let us create a file NEWFILE.TXT through UTL_FILE

Connect with Scott and execute the following procedure

Create or Replace procedure UTLTEST as

f1 utl_file.file_type;
begin
-- Open a file in write mode
f1 := utl_file.fopen('DBDIR','NEWFILE.TXT','W');
-- Write a line to a file
utl_file.put_line(f1,'1. This is a test of UTL_FILE packages');
utl_file.put_line(f1,'2. Oracle has added a new procedures in the package');
utl_file.put_line(f1,'3. We will see all the procedure one by one');
-- Close a file
utl_file.fclose(f1);
end;
/
show error;

SQL> execute utltest;

The execution of the above procedure will create a file in C:\TEMP\LOC1 with a name
NEWFILE.TXT
===============================================================
TEST FOR COPYING A FILE ON SAME LOCATION.

PROCEDURE FCOPY

Argument Name Type In/Out Default?

------------------------------ ----------------------- ------ --------
SRC_LOCATION VARCHAR2 IN
SRC_FILENAME VARCHAR2 IN
DEST_LOCATION VARCHAR2 IN
DEST_FILENAME VARCHAR2 IN
START_LINE BINARY_INTEGER IN DEFAULT
END_LINE BINARY_INTEGER IN DEFAULT

create or replace procedure UTLTESTCOPY as

f1 utl_file.file_type;
begin
f1 := utl_file.fopen('DBDIR','NEWFILE.TXT','R');
UTL_FILE.FCOPY(SRC_LOCATION=>'DBDIR',
SRC_FILENAME=>'NEWFILE.TXT',
DEST_LOCATION=>'DBDIR',
DEST_FILENAME=>'NEWFILECOPY.TXT');
UTL_FILE.FCLOSE(F1);
END;
/
SHOW ERRORS

Sql> Execute UTLTESTCOPY;

You will see two files now NEWFILE.TXT as well as NEWFILECOPY.TXT

By opening the NEWFILE.TXT is open in 'W' will make it blank.
===============================================================

TEST FOR COPY A FILE ON DIFFERENT LOCATION.

Create or Replace procedure UtlTestCopyDIffLoc as

f1 utl_file.file_type;
begin
f1 := utl_file.fopen('DBDIR','NEWFILE.TXT','R');
UTL_FILE.FCOPY(SRC_LOCATION=>'DBDIR',
SRC_FILENAME=>'NEWFILE.TXT',
DEST_LOCATION=>'DBDIR2',
DEST_FILENAME=>'NEWFILECOPY.TXT',
START_LINE=>2,
END_LINE=>4);
UTL_FILE.FCLOSE(F1);
END;
/
SHOW ERRORS
Sql> Execute UtlTestCopyDiffLoc

You will see a file NEWFILE.TXT in C:\TEMP\LOC1 and COPYNEWFILE.TXT in

C:\TEMP\LOC2.
===============================================================
TEST FOR COPY A FILE ON NETWORK LOCATION

SQL> create or replace directory networkdir as '\\ORCL8i\TEMP';

Directory created.

SQL> grant read on directory networkdir to scott;

Grant succeeded.

Create or Replace procedure UTLTESTCOPY as

f1 utl_file.file_type;
begin
f1 := utl_file.fopen('DBDIR','NEWFILE.TXT','R');
UTL_FILE.FCOPY(SRC_LOCATION=>'DBDIR',
SRC_FILENAME=>'NEWFILE.TXT',
DEST_LOCATION=>'NETWORKDIR',
DEST_FILENAME=>'NEWFILECOPY.TXT');
UTL_FILE.FCLOSE(F1);
END;
/
SHOW ERRORS

To make this work you have to controlpanel->Adminstrative tools->Services-

>OracleServiceXXXX
Right click on service and click properties -> Press LOG ON->click log on as add the username
and
password on which remote machine is accesible. Stop and start the service after that.
===============================================================
TEST FOR MOVING AND RENAMING A FILE

PROCEDURE FRENAME

Argument Name Type In/Out Default?

------------------------------ ----------------------- ------ --------
SRC_LOCATION VARCHAR2 IN
SRC_FILENAME VARCHAR2 IN
DEST_LOCATION VARCHAR2 IN
DEST_FILENAME VARCHAR2 IN
OVERWRITE BOOLEAN IN DEFAULT

Create or Replace procedure UTLTESTRENAME as

begin
UTL_FILE.FRENAME(SRC_LOCATION=>'DBDIR',
SRC_FILENAME=>'NEWFILE.TXT',
DEST_LOCATION=>'DBDIR2',
DEST_FILENAME=>'NEWFILE4.TXT',
OVERWRITE=>FALSE);
END;
/
SHOW ERRORS

SQL> execute UTLTESTRENAME;

It will move the file NEWFILE.TXT from C:\TEMP\LOC1 directory and C:\TEMP\LOC2
directory and rename it as NEWFILE4.TXT

It copies and rename a files

If the file is not there ERROR at line 1:
ORA-29283: invalid file operation
ORA-06512: at "SYS.UTL_FILE", line 18

If the file is in sharing mode you can not rename it.

You will get ORA-29292: file rename operation failed or if the overwrite is false
than the destination location should not have the file with the same name.

===============================================================
TEST FOR GETTING ATTRIBUTE OF A FILE

PROCEDURE FGETATTR

Argument Name Type In/Out Default?

------------------------------ ----------------------- ------ --------
LOCATION VARCHAR2 IN
FILENAME VARCHAR2 IN
FEXISTS BOOLEAN OUT
FILE_LENGTH NUMBER OUT
BLOCK_SIZE BINARY_INTEGER OUT

Create or Replace procedure UTLTESTattr as

Present boolean;
FlENGTH number;
bsize pls_integer;
begin
UTL_FILE.FGETATTR(LOCATION=>'DBDIR2',
FILENAME=>'NEWFILE4.TXT',
FEXISTS=>PRESENT,
FILE_LENGTH=>FLENGTH,
BLOCK_SIZE=>BSize);
If present then
dbms_output.put_line('FILE FOUND');
dbms_output.put_line('HAVING LENGTH ='||FLENGTH);
dbms_output.put_line('HAVING BLOCK SIZE ='||BSIZE);
end if;
END;
/
SHOW ERRORS

SQL> execute utltestattr

FILE FOUND
HAVING LENGTH =138
HAVING BLOCK SIZE =0

PL/SQL procedure successfully completed.

LENGTH is the number of chars with spaces found in the file NEWFILE4.TXT

Following Exceptions are valid for UTL_FILE

file_open
charsetmismatch
invalid_path
invalid_mode
invalid_filehandle
invalid_operation
read_error
write_error
internal_error
invalid_maxlinesize
invalid_filename
access_denied
invalid_offset
delete_failed
rename_failed
===============================================================
create or replace directory dir_temp as 'c:\temp';

grant read, write on directory dir_temp to scott;

declare
f utl_file.file_type;
begin
f := utl_file.fopen('DIR_TEMP', 'something.txt', 'w');
utl_file.put_line(f, 'line one: some text');
utl_file.put_line(f, 'line two: more text');
utl_file.fclose(f);
end;
===============================================================
SQL> create or replace directory DIR_UTL as 'C:\UTLFOLDER';

Directory created.

Grant read,write on directory dbdir to Scott;

CREATE OR REPLACE PROCEDURE sal_status

(p_filedir IN VARCHAR2, p_filename IN VARCHAR2)
IS
v_filehandle UTL_FILE.FILE_TYPE;
CURSOR emp_info IS
SELECT ename, sal, deptno
FROM emp
ORDER BY deptno;
v_newdeptno emp.deptno%TYPE;
v_olddeptno emp.deptno%TYPE := 0;
BEGIN
v_filehandle := UTL_FILE.FOPEN (p_filedir, p_filename,'w');
UTL_FILE.PUTF (v_filehandle,'SALARY REPORT: GENERATED ON %s\n',
SYSDATE);
UTL_FILE.NEW_LINE (v_filehandle);
FOR v_emp_rec IN emp_info
LOOP
v_newdeptno := v_emp_rec.deptno;
IF v_newdeptno <> v_olddeptno THEN
UTL_FILE.PUTF (v_filehandle, 'DEPARTMENT: %s\n',v_emp_rec.deptno);
END IF;
UTL_FILE.PUTF (v_filehandle,' EMPLOYEE: %s earns: %s\n',
v_emp_rec.ename, v_emp_rec.sal);
v_olddeptno := v_newdeptno;
END LOOP;
UTL_FILE.PUT_LINE (v_filehandle, '*** END OF REPORT ***');
 UTL_FILE.FCLOSE (v_filehandle);
EXCEPTION
WHEN UTL_FILE.INVALID_FILEHANDLE THEN
RAISE_APPLICATION_ERROR (-20001, 'Invalid File.');
WHEN UTL_FILE.WRITE_ERROR THEN
RAISE_APPLICATION_ERROR (-20002, 'Unable to write to file');
END sal_status;

exec sal_status ('ECX_UTL_XSLT_DIR_OBJ','UTLF1.TXT');

OutPut
----------
SALARY REPORT: GENERATED ON 08-MAR-01
DEPARTMENT: 10
EMPLOYEE: Whalen earns: 4400
DEPARTMENT: 20
EMPLOYEE: Hartstein earns: 13000
EMPLOYEE: Fay earns: 6000
DEPARTMENT: 30
EMPLOYEE: Raphaely earns: 11000
EMPLOYEE: Khoo earns: 3100
...
DEPARTMENT: 100
EMPLOYEE: Greenberg earns: 12000
...
DEPARTMENT: 110
EMPLOYEE: Higgins earns: 12000
EMPLOYEE: Gietz earns: 8300
EMPLOYEE: Grant earns: 7000
*** END OF REPORT ***
===============================================================
CREATE OR REPLACE PROCEDURE utl_prc
(p_filedir IN VARCHAR2, p_filename IN VARCHAR2)
IS
v_filehandle UTL_FILE.FILE_TYPE;
CURSOR emp_info IS
SELECT ename, sal, deptno
FROM emp
ORDER BY deptno;
BEGIN
v_filehandle := UTL_FILE.FOPEN (p_filedir, p_filename,'w');
UTL_FILE.PUTF (v_filehandle,'SALARY REPORT: GENERATED ON %s\n',
SYSDATE);
UTL_FILE.NEW_LINE (v_filehandle);
FOR v_emp_rec IN emp_info
LOOP
UTL_FILE.PUTF (v_filehandle, 'EMP Table:
%s\n',v_emp_rec.deptno,v_emp_rec.ename, v_emp_rec.sal);
END LOOP;
UTL_FILE.PUT_LINE (v_filehandle, '*** END OF REPORT ***');
UTL_FILE.FCLOSE (v_filehandle);
EXCEPTION
WHEN UTL_FILE.INVALID_FILEHANDLE THEN
RAISE_APPLICATION_ERROR (-20001, 'Invalid File.');
WHEN UTL_FILE.WRITE_ERROR THEN
RAISE_APPLICATION_ERROR (-20002, 'Unable to write to file');
END utl_prc;
===============================================================