Oracle內建包UTL_FILE使用說明

最近用到了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 (
      location     IN VARCHAR2,
      filename     IN VARCHAR2,
      open_mode    IN VARCHAR2,
      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異常。
FOPEN 會丟擲以下異常
UTL_FILE.INVALID_MODE
UTL_FILE.INVALID_OPERATION
UTL_FILE.INVALID_PATH
UTL_FILE.INVALID_MAXLINESIZE [Page]
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會產生以下異常 [Page]
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); [Page]
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  

來自 “ ITPUB部落格 ” ，連結：http://blog.itpub.net/219982/viewspace-524558/，如需轉載，請註明出處，否則將追究法律責任。