Oracle內建包UTL_FILE使用說明

在數據庫的開發中，當PL/SQL語句很復雜的時候，我想寫一些Log，就像java的Log4j那樣。這樣就可以很好的跟蹤程序的運行情況。在網上找到的文章不是很好用，修改了一下。

1：在Oracle服務器上建立一個目錄并指定權限（我這個是unix的。windows用c:/tmp之類的就行）

CREATE DIRECTORY TEMP AS '/tmp';
GRANT READ,WRITE ON DIRECTORY TEMP TO PUBLIC;
GRANT   EXECUTE ON SYS.UTL_FILE TO YOU_USER_NAME;

如果出現權限錯誤的話，注意自己登陸的方式，我是用oralce用戶TelNet到Unix上的，然后connect / as sysdba。（windows 用戶應該是：用sys用戶登錄到數據庫(ora9i):conn sys/password@oraclesid as sysdba ，sys用戶的缺省密碼和system一樣，都是manager）

2：寫Log文件的SQL語句如下：

declare
file_handle utl_file.file_type;
buff varchar2(20);
cursor c1 is select acloumn from t_atable;
begin
file_handle := utl_file.fopen('TEMP',log.txt','w');
open c1;
loop
    fetch c1 into buff;
    exit when c1%notfound;
    utl_file.put_line(file_handle,buff);
   end loop;
   close c1;
   utl_file.fclose(file_handle);
end;

這樣，就應該可以了，file_handle := utl_file.fopen('TEMP',log.txt','w');中的'w'是指write,也可以是'a',append.

封裝后是這樣的：

procedure writeLog(logMessage in Varchar2) is
begin
    IF logSwitch THEN
      file_handle := utl_file.fopen('TEMP','x.txt','w');
      utl_file.put_line(file_handle,logMessage);
      utl_file.fclose(file_handle);
    END IF;
end;

其中logSwitch 是boolean型，我定義在包中的。如果直接用的話可以是procedure writeLog(logMessage in Varchar2, logSwitch in boolean )

/************************************************************************************/

最近用到了Oracle的包UTL_FILE，網上卻沒找到關于它的函數，過程使用說明，雖然都不是很難的東西，但簡單列出來，也能提高些效率。

于是有了這篇文。
以下翻譯來自《Oracle Built-in Packages》的第六章，只翻譯了部分，想了解的更詳細，請參考原文。http://www.oreilly.com/catalog/oraclebip/chapter/ch06.html

FOPEN
IS_OPEN
GET_LINE
PUT
NEW_LINE
PUT_LINE
PUTF
FFLUSH
FCLOSE
FCLOSE_ALL

UTL_FILE.FOPEN 用法
FOPEN會打開指定文件并返回一個文件句柄用于操作文件。
所有PL/SQL版本:                 Oracle 8.0版及以上:
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;

參數

location
文件地址

filename
文件名

openmode
打開文件的模式（參見下面說明）

max_linesize
文件每行最大的字符數，包括換行符。最小為1，最大為32767

3種文件打開模式：
R 只讀模式。一般配合UTL_FILE的GET_LINE來讀文件。
W 寫（替換）模式。文件的所有行會被刪除。PUT, PUT_LINE, NEW_LINE, PUTF和FFLUSH都可使用
A 寫（附加）模式。原文件的所有行會被保留。在最末尾行附加新行。PUT, PUT_LINE, NEW_LINE, PUTF和FFLUSH都可使用

打開文件時注意以下幾點：
文件路徑和文件名合起來必須表示操作系統中一個合法的文件。
文件路徑必須存在并可訪問；FOPEN并不會新建一個文件夾。
如果你想打開文件進行讀操作，文件必須存在；如果你想打開文件進行寫操作，文件不存在時，會新建一個文件。
如果你想打開文件進行附加操作，文件必須存在。A模式不同于W模式。文件不存在時，會拋出INVALID_OPERATION異常。

注: 我用A模式時文件不存在的話會自動創建, 當目錄不存在的時候拋出UTL_FILE.INVALID_OPERATION異常 (linux系統, oracle 9i)

FOPEN 會拋出以下異常
UTL_FILE.INVALID_MODE
UTL_FILE.INVALID_OPERATION
UTL_FILE.INVALID_PATH
UTL_FILE.INVALID_MAXLINESIZE

UTL_FILE.IS_OPEN用法
如果文件句柄指定的文件已打開，返回TRUE，否則FALSE

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

UTL_FILE只提供一個方法去讀取數據：GET_LINE

UTL_FILE.GET_LINE用法
讀取指定文件的一行到提供的緩存。
PROCEDURE UTL_FILE.GET_LINE
   (file IN UTL_FILE.FILE_TYPE,
    buffer OUT VARCHAR2);

file
由FOPEN返回的文件句柄

buffer
讀取的一行數據的存放緩存

buffer必須足夠大。否則，會拋出VALUE_ERROR 異常。行終止符不會被傳進buffer。

異常
NO_DATA_FOUND
VALUE_ERROR
UTL_FILE.INVALID_FILEHANDLE
UTL_FILE.INVALID_OPERATION
UTL_FILE.READ_ERROR

UTL_FILE.PUT用法
在當前行輸出數據
PROCEDURE UTL_FILE.PUT
    (file IN UTL_FILE.FILE_TYPE,
    buffer OUT VARCHAR2);
file
由FOPEN返回的文件句柄
buffer
包含要寫入文件的數據緩存；Oracle8.0.3及以上最大允許32kB，早期版本只有1023B

UTL_FILE.PUT輸出數據時不會附加行終止符。

UTL_FILE.PUT會產生以下異常
UTL_FILE.INVALID_FILEHANDLE
UTL_FILE.INVALID_OPERATION
UTL_FILE.WRITE_ERROR

UTL_FILE.NEW_LINE
在當前位置輸出新行或行終止符，必須使用NEW_LINE來結束當前行，或者使用PUT_LINE輸出帶有行終止符的完整行數據。

PROCEDURE UTL_FILE.NEW_LINE
   (file IN UTL_FILE.FILE_TYPE,
    lines IN NATURAL := 1);
file
由FOPEN返回的文件句柄
lines
要插入的行數

如果不指定lines參數，NEW_LINE會使用默認值1，在當前行尾換行。如果要插入一個空白行，可以使用以下語句：
UTL_FILE.NEW_LINE (my_file, 2);
如果lines參數為0或負數，什么都不會寫入文件。

NEW_LINE會產生以下異常
VALUE_ERROR
UTL_FILE.INVALID_FILEHANDLE
UTL_FILE.INVALID_OPERATION
UTL_FILE.WRITE_ERROR
例子
如果要在UTL_FILE.PUT后立刻換行，可以如下例所示：
PROCEDURE add_line (file_in IN UTL_FILE.FILE_TYPE, line_in IN VARCHAR2)
IS
BEGIN
   UTL_FILE.PUT (file_in, line_in);
   UTL_FILE.NEW_LINE (file_in);
END;

UTL_FILE.PUT_LINE
輸出一個字符串以及一個與系統有關的行終止符
PROCEDURE UTL_FILE.PUT_LINE
    (file IN UTL_FILE.FILE_TYPE,
    buffer IN VARCHAR2);
file
由FOPEN返回的文件句柄
buffer
包含要寫入文件的數據緩存；Oracle8.0.3及以上最大允許32kB，早期版本只有1023B
在調用UTL_FILE.PUT_LINE前，必須先打開文件。
UTL_FILE.PUT_LINE會產生以下異常
UTL_FILE.INVALID_FILEHANDLE
UTL_FILE.INVALID_OPERATION
UTL_FILE.WRITE_ERROR

例子
這里利用UTL_FILE.PUT_LINE從表emp讀取數據到文件：
PROCEDURE emp2file
IS
   fileID UTL_FILE.FILE_TYPE;
BEGIN
   fileID := UTL_FILE.FOPEN ('/tmp', 'emp.dat', 'W');

   /* Quick and dirty construction here! */
   FOR emprec IN (SELECT * FROM emp)
   LOOP
      UTL_FILE.PUT_LINE
         (TO_CHAR (emprec.empno) || ',' ||
          emprec.ename || ',' ||
          ...
          TO_CHAR (emprec.deptno));
   END LOOP;

   UTL_FILE.FCLOSE (fileID);
END;
PUT_LINE相當于PUT后加上NEW_LINE；也相當于PUTF的格式串"%s/n"。

UTL_FILE.PUTF
以一個模版樣式輸出至多5個字符串，類似C中的printf

PROCEDURE UTL_FILE.PUTF
    (file 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
由FOPEN返回的文件句柄
format
決定格式的格式串
argN
可選的5個參數，最多5個

格式串可使用以下樣式
%s
在格式串中可以使用最多5個%s，與后面的5個參數一一對應
/n
換行符。在格式串中沒有個數限制
%s會被后面的參數依次填充，如果沒有足夠的參數，%s會被忽視，不被寫入文件

UTL_FILE.PUTF會產生以下異常
UTL_FILE.INVALID_FILEHANDLE
UTL_FILE.INVALID_OPERATION
UTL_FILE.WRITE_ERROR

UTL_FILE.FFLUSH
確保所有數據寫入文件。
PROCEDURE UTL_FILE.FFLUSH (file IN UTL_FILE.FILE_TYPE);
file
由FOPEN返回的文件句柄

操作系統可能會緩存數據來提高性能。因此可能調用put后，打開文件卻看不到寫入的數據。在關閉文件前要讀取數據的話可以使用UTL_FILE.FFLUSH。
典型的使用方法包括分析執行進度和調試紀錄。
UTL_FILE.FFLUSH會產生以下異常
UTL_FILE.INVALID_FILEHANDLE
UTL_FILE.INVALID_OPERATION
UTL_FILE.WRITE_ERROR

UTL_FILE.FCLOSE
關閉文件
PROCEDURE UTL_FILE.FCLOSE (file IN OUT FILE_TYPE);
file
由FOPEN返回的文件句柄

注意file是一個IN OUT參數，因為在關閉文件后會設置為NULL
當試圖關閉文件時有緩存數據未寫入文件，會拋出WRITE_ERROR異常

UTL_FILE.FCLOSE會產生以下異常
UTL_FILE.INVALID_FILEHANDLE
UTL_FILE.WRITE_ERROR

UTL_FILE.FCLOSE_ALL
關閉所有已打開的文件
PROCEDURE UTL_FILE.FCLOSE_ALL;

在結束程序時要確保所有打開的文件已關閉，可使用FCLOSE_ALL
也可以在EXCEPTION使用，當異常退出時，文件也會被關閉。
EXCEPTION
   WHEN OTHERS
  
THEN
      UTL_FILE.FCLOSE_ALL;
      ... other clean up activities ...
END;

注意：當使用FCLOSE_ALL關閉所有文件時，文件句柄并不會標記為NULL，使用IS_OPEN會返回TRUE。但是，那些關閉的文件不能執行讀寫操作（除非你再次打開文件）。
UTL_FILE.FCLOSE_ALL會產生以下異常
UTL_FILE.WRITE_ERROR

//***************************************************************************************************************

---------------------------------------------------------------------------------------------------寫日志文件
--利用utl_file包，在此之前，要注意設置好utl_file_dir初始化參數

1. 以oracle用戶登錄，在oracle目錄(或其子目錄)下創建目錄：$mkdir tgm_test
2. 創建數據庫中的目錄對象：create or replace directory TGM_LOG_DIR as '/home/oracle/tgm_test';

3. 以管理員用戶登陸，如：sqlplus "/as sysdba";
4. 設置可操作目錄，alter system set utl_file_dir='/home/oracle/tgm_test' scope=spfile;
5. 授權給指定用戶，以便執行utl_file： GRANT EXECUTE ON utl_file TO train;

6. conn train/train 就可以正常使用utl_file了
7. exec write_log('this is a test!');

----3，4，5 似乎可以省略掉

------------------------------------write_log存儲過程

CREATE OR REPLACE PROCEDURE write_log(text_context VARCHAR2) IS
file_handle utl_file.file_type;
write_content VARCHAR2(1024);
file_name VARCHAR2(50);
BEGIN
--open file
file_name := 'tgm.log';
file_handle := utl_file.fopen('TGM_LOG_DIR', file_name, 'w'); --寫模式
write_content := to_char(SYSDATE, 'yyyy-mm-dd hh34:mi:ss') || '--->' || text_context;
--write file
IF utl_file.is_open(file_handle)
THEN
    dbms_output.put_line('is open!');
   utl_file.put_line(file_handle, write_content);
END IF;
--close file
utl_file.fclose(file_handle);
EXCEPTION
WHEN OTHERS THEN
   BEGIN
    IF utl_file.is_open(file_handle)
    THEN
     utl_file.fclose(file_handle);
    END IF;
   EXCEPTION
    WHEN OTHERS THEN
     NULL;
   END;
END write_log;