1. PL/SQLパッケージ・リファレンス
  2. UTL_FILE

11 UTL_FILE

UTL_FILEパッケージを使用して、PL/SQLプログラムでオペレーティング・システムのテキスト・ファイルの読込みと書込みができます。UTL_FILEは、オペレーティング・システムのストリーム・ファイルI/Oの制約付きバージョンを提供します。

この章の内容は次のとおりです。

UTL_FILEの使用

セキュリティ・モデル

UTL_FILEは、ディレクトリtimesten_home/plsql/utl_file_tempに制限されます。

アクセスは、このディレクトリのサブディレクトリにまで拡張されることはありません。また、アクセスでは、ファイル・システムに対する権限チェックが行われます。必要に応じて、インスタンス管理者は、UTL_FILEアクセス権限を特定のユーザーに付与できます。ユーザーは、UTL_FILEサブプログラムのロケーション・パラメータに文字列'UTL_FILE_TEMP'を使用して、このUTL_FILEディレクトリを参照できます。この事前定義済の文字列は、Oracle Databaseのディレクトリ・オブジェクト名と同じ方法で使用されます。

UTL_FILEは、目的のアクセス制限を回避するように使用できるリンクで使用することはできません。ファイル名としてリンクを指定すると、FOPENが失敗し、エラーが発生します。

TimesTenの直接接続の場合、アプリケーション所有者がファイルの所有者です。クライアント/サーバー接続の場合、サーバー所有者がファイルの所有者です。

UTL_FILE_DIRアクセスは、TimesTenでサポートされていません。

ヒント:

  • デフォルトでは、ユーザーにはUTL_FILEに対する実行権限はありません。TimesTenでUTL_FILEを使用するには、次の例に示すように、ADMINユーザーまたはインスタンス管理者が、明示的にGRANT EXECUTEを実行して権限を付与する必要があります。 

    GRANT EXECUTE ON SYS.UTL_FILE TO scott;

  • ファイルへのアクセスに必要な権限は、オペレーティング・システムに固有です。UTL_FILE権限によって、ユーザーには、UTL_FILEディレクトリ内のすべてのファイルに対する読取りと書込みのアクセス権限が与えられますが、サブディレクトリ内のファイルにはアクセスできません。

  • 無効なUTL_FILEオプションを適用しようとすると、予期しない動作が発生します。

操作上のノート

UTL_FILEは、ディレクトリtimesten_home/plsql/utl_file_tempに制限されます。アクセスは、このディレクトリのサブディレクトリにまで拡張されることはありません。また、アクセスでは、ファイル・システムに対する権限チェックが行われます。必要に応じて、インスタンス管理者は、UTL_FILEアクセス権限を特定のユーザーに付与できます。ユーザーは、UTL_FILEサブプログラムのロケーション・パラメータに文字列'UTL_FILE_TEMP'を使用することによって、このUTL_FILEディレクトリを参照できます。この事前定義済の文字列は、Oracle Databaseのディレクトリ・オブジェクト名と同じ方法で使用されます。

ファイルの場所とファイル名の各パラメータは、別々の文字列としてFOPENファンクションに指定されるため、ファイルの場所は、utl_file_tempディレクトリと照合してチェックできます。ファイルの場所と名前は、システム上の有効なファイル名である必要があり、ディレクトリはアクセス可能である必要があります。utl_file_tempのサブディレクトリにはアクセスできません。

UTL_FILEは読込み要求に対する行終了記号を暗黙的に解析するため、GET_LINEコールに対して戻されるバイト数に影響を与えます。たとえば、GET_LINEのlenパラメータは、文字データの要求バイト数を指定します。実際にユーザーに戻されるバイト数は、次のいずれかの最も小さい値になります。

  • GET_LINE lenパラメータ値

  • 次の行終了文字までのバイト数

  • FOPENによって指定されるmax_linesizeパラメータ値

FOPEN max_linesizeパラメータは、1から32767の範囲内の数字である必要があります。指定しない場合は、デフォルト値の1024が設定されます。GET_LINE lenパラメータは、1から32767の範囲内の数字である必要があります。指定がない場合は、デフォルト値のmax_linesizeが指定されます。max_linesizeとlenに異なる値が指定された場合は、小さい方の値が優先されます。

1つの文字セットにエンコードされたデータが読み込まれ、そのデータを別の文字セットにエンコードするようにグローバリゼーション・サポートが命じられた(NLS_LANGなどを使用して)場合、結果は不定です。NLS_LANGを設定する場合は、データベースの文字セットと同じものにする必要があります。

ルールおよび制限

LinuxまたはUNIXでのCシェル環境変数などのオペレーティング・システム固有のパラメータは、ファイルの場所またはファイル名のパラメータでは使用できません。

UTL_FILEのI/O機能は、標準のオペレーティング・システムに備えられたストリーム・ファイルのI/O(OPEN、GET、PUT、CLOSE)機能に類似していますが、いくつかの点で制限があります。たとえば、FOPENファンクションをコールすると、ファイル・ハンドルが戻されますが、後続のGET_LINEまたはPUTのコールでこのファイル・ハンドルを使用し、ファイルへのストリームI/Oを実行します。ファイルのI/Oが完了した場合、FCLOSEをコールして出力を完了し、そのファイルに関連付けられたリソースを解放します。

例外

この項では、UTL_FILEサブプログラムによってスローされる例外について説明します。

ノート:

ここに示す例外に加え、UTL_FILEのプロシージャおよびファンクションでは、NO_DATA_FOUND、VALUE_ERRORなど、事前定義済のPL/SQL例外が発生する可能性があります。詳細は、Oracle Database PL/SQL言語リファレンスの事前定義済の例外を参照してください。

表11-1 UTL_FILEパッケージの例外

例外名 説明

ACCESS_DENIED

ファイルの場所に対するアクセス許可が拒否されました。

CHARSETMISMATCH

ファイルはFOPEN_NCHARを使用してオープンされますが、後のI/O操作ではPUTF、GET_LINEなどのNCHAR以外のファンクションを使用します。また、ファイルはFOPENを使用してオープンされますが、後のI/O操作ではPUTF_NCHAR、GET_LINE_NCHARなどのNCHARファンクションを使用します。

DELETE_FAILED

要求したファイルの削除操作に失敗しました。

FILE_OPEN

要求した操作は、ファイルがオープンしているため失敗しました。

INTERNAL_ERROR

PL/SQL内で不明なエラーが発生しました。

INVALID_FILEHANDLE

ファイル・ハンドルが無効です。

INVALID_FILENAME

filenameパラメータが無効です。

INVALID_MAXLINESIZE

FOPENのmax_linesize値が有効範囲外です。1から32767の範囲内にしてください。

INVALID_MODE

FOPENのopen_modeパラメータが無効です。

INVALID_OFFSET

原因は次のいずれかです。

  • ABSOLUTE_OFFSETはNULLで、RELATIVE_OFFSETはNULLです。

  • ABSOLUTE_OFFSETは0未満です。

  • ファイルの終わりを超える検索がどちらかのオフセットで発生。

INVALID_OPERATION

要求どおりにファイルをオープンできないか、または操作できません。

INVALID_PATH

ファイルの場所または名前が無効です。

LENGTH_MISMATCH

CHARまたはRAWデータの長さが不一致。

READ_ERROR

読取り操作中にオペレーティング・システムのエラーが発生しました。

RENAME_FAILED

要求したファイル名変更操作に失敗しました。

WRITE_ERROR

書込み操作中にオペレーティング・システムのエラーが発生しました。

例

例1: GET_LINE

この例では、GET_LINEプロシージャを使用してファイルからの読取りを行います。 

DECLARE 
  V1 VARCHAR2(32767); 
  F1 UTL_FILE.FILE_TYPE; 
BEGIN 
  -- In this example MAX_LINESIZE is less than GET_LINE's length request 
  -- so number of bytes returned is 256 or less if a line terminator is seen.
  F1 := UTL_FILE.FOPEN('UTL_FILE_TEMP','u12345.tmp','R',256); 
  UTL_FILE.GET_LINE(F1,V1,32767); 
  DBMS_OUTPUT.PUT_LINE('Get line: ' || V1);
  UTL_FILE.FCLOSE(F1); 
 
  -- In this example, FOPEN's MAX_LINESIZE is NULL and defaults to 1024, 
  -- so number of bytes returned is 1024 or less if line terminator is seen. 
  F1 := UTL_FILE.FOPEN('UTL_FILE_TEMP','u12345.tmp','R'); 
  UTL_FILE.GET_LINE(F1,V1,32767); 
  DBMS_OUTPUT.PUT_LINE('Get line: ' || V1);
  UTL_FILE.FCLOSE(F1); 
 
  -- GET_LINE doesn't specify a number of bytes, so it defaults to 
  -- same value as FOPEN's MAX_LINESIZE which is NULL and defaults to 1024. 
  -- So number of bytes returned is 1024 or less if line terminator is seen. 
  F1 := UTL_FILE.FOPEN('UTL_FILE_TEMP','u12345.tmp','R'); 
  UTL_FILE.GET_LINE(F1,V1); 
  DBMS_OUTPUT.PUT_LINE('Get line: ' || V1);
  UTL_FILE.FCLOSE(F1); 
END;

テスト・ファイル(utl_file_tempディレクトリにあるu12345.tmp)を検討します。 

This is line 1.
This is line 2.
This is line 3.
This is line 4.
This is line 5.

例の結果は、次の出力のようになり、最初の行のみが繰り返し取得されます。

Get line: This is line 1.
Get line: This is line 1.
Get line: This is line 1.
 
PL/SQL procedure successfully completed.

例2: PUTF

この例では、PUTFプロシージャを使用して、ファイルの末尾にコンテンツが追加されます。 

declare
   handle utl_file.file_type;
   my_world  varchar2(4) := 'Zork';
begin
   handle := utl_file.fopen('UTL_FILE_TEMP','u12345.tmp','a');
   utl_file.putf(handle, '\nHello, world!\nI come from %s with %s.\n', my_world, 
                         'greetings for all earthlings');
   utl_file.fflush(handle);
   utl_file.fclose(handle);
end;

これによって、次のものがutl_file_tempディレクトリのファイルu12345.tmpに追加されます。 

Hello, world!
I come from Zork with greetings for all earthlings.

例3: GET_RAW

このプロシージャは、GET_RAWプロシージャを使用して、指定したファイルからRAWデータを取得します。これは、EXCEPTION処理のNO_DATA_FOUNDの処理によって、データの最後に到達すると終了します。 

CREATE OR REPLACE PROCEDURE getraw(n IN VARCHAR2) IS
  h     UTL_FILE.FILE_TYPE;
  Buf   RAW(32767);
  Amnt  CONSTANT BINARY_INTEGER := 32767;
BEGIN
  h := UTL_FILE.FOPEN('UTL_FILE_TEMP', n, 'r', 32767);
  LOOP
    BEGIN
      UTL_FILE.GET_RAW(h, Buf, Amnt);
 
      -- Do something with this chunk
      DBMS_OUTPUT.PUT_LINE('This is the raw data:');
      DBMS_OUTPUT.PUT_LINE(Buf);
    EXCEPTION WHEN No_Data_Found THEN
      EXIT;
    END;
  END LOOP;
  UTL_FILE.FCLOSE (h);
END;

utl_file_tempディレクトリ内のファイルu12345.tmpの次のコンテンツを検討します。 

hello world!

例では、次のような出力が生成されます。

Command> begin
            getraw('u12345.tmp');
         end;
         /
This is the raw data:
68656C6C6F20776F726C64210A
 
PL/SQL procedure successfully completed.

データ構造

UTL_FILEパッケージは、次のレコード・タイプを定義します。

レコード・タイプ

FILE_TYPEレコード・タイプ

FILE_TYPEの内容は、UTL_FILEパッケージ専用です。このレコードのコンポーネントを参照または変更しないでください。 

TYPE file_type IS RECORD (
   id          BINARY_INTEGER, 
   datatype    BINARY_INTEGER,
   byte_mode   BOOLEAN);

フィールド

表11-2 FILE_TYPEのフィールド

フィールド 説明

id

内部ファイル・ハンドル番号(数値)を示します。

datatype

ファイルのタイプを示します(CHARファイル、NCHARファイルまたは他のファイル(バイナリ))。

byte_mode

ファイルがバイナリ・ファイルとしてオープンされたか、テキスト・ファイルとしてオープンされたかを示します。

ヒント:

Oracle Databaseでは、データベース・セッション間または単一セッション内でのFILE_TYPE値の永続性は保証されていません。ファイル・ハンドルのクローン化やダミー・ファイルの使用を試みると、予測できない結果が生じる可能性があります。

ノート:

  • PLS_INTEGERデータ・タイプとBINARY_INTEGERデータ・タイプは同じです。このドキュメントでは、リファレンス情報でデータ・タイプ(表タイプ、レコード・タイプ、サブプログラム・パラメータ、サブプログラム戻り値など)を示す場合にBINARY_INTEGERを使用しますが、説明および例ではいずれも使用される場合があります。

  • INTEGERデータ・タイプとNUMBER(38)データ・タイプも同じです。このドキュメントでは、全体をとおしてINTEGERを使用します。

UTL_FILEのサブプログラム

表11-3に、UTL_FILEのサブプログラムの概要と各サブプログラムの詳細な説明を示します。

表11-3 UTL_FILEサブプログラム

サブプログラム 説明

FCLOSEプロシージャ

ファイルをクローズします。

FCLOSE_ALLプロシージャ

オープンしているファイル・ハンドルをすべてクローズします。

FCOPYプロシージャ

ファイルの連続部分を新規に作成したファイルにコピーします。

FFLUSHプロシージャ

保留中のすべての出力を物理的にファイルに書き込みます。

FGETATTRプロシージャ

ファイルの属性を読み取って返します。

FGETPOSファンクション

ファイル内の現行の相対オフセット位置をバイト数で戻します。

FOPENファンクション

入力用または出力用にファイルをオープンします。

FOPEN_NCHARファンクション

入力用または出力用にファイルをUnicodeでオープンします。

FREMOVEプロシージャ

十分な権限がある場合にファイルを削除します。

FRENAMEプロシージャ

UNIXのmvファンクションと同じように、既存のファイルに新規の名前を指定します。

FSEEKプロシージャ

指定したバイトの数だけ、ファイル内でポインタを前方または後方に調整します。

GET_LINEプロシージャ

オープンしているファイルからテキストを読み込みます。

GET_LINE_NCHARプロシージャ

オープンしているファイルからテキストをUnicodeで読み込みます。

GET_RAWプロシージャ

RAW文字列値をファイルから読み込み、読み込んだバイトの数だけ、ファイルのポインタを前方に調整します。

IS_OPENファンクション

ファイル・ハンドルが、オープンしているファイルを参照しているかどうかを判別します。

NEW_LINEプロシージャ

1つ以上のオペレーティング・システム固有の行終了記号をファイルに書き込みます。

PUTプロシージャ

ファイルに1つの文字列を書き込みます。

PUT_LINEプロシージャ

ファイルに1行書き込み、それによってオペレーティング・システム固有の行終了記号を1つ追加します。

PUT_LINE_NCHARプロシージャ

ファイルにUnicode行を1行書き込みます。

PUT_NCHARプロシージャ

ファイルに1つのUnicode文字列を書き込みます。

PUT_RAWプロシージャ

RAWデータ値を入力として受け入れ、出力バッファに書き込みます。

PUTFプロシージャ

これは、PUTと同じですが、フォーマットを行います。

PUTF_NCHARプロシージャ

これは、PUT_NCHARと同じですが、フォーマットを行います。

FCLOSEプロシージャ

このプロシージャは、ファイル・ハンドルが示すオープン・ファイルをクローズします。

構文

UTL_FILE.FCLOSE (
   file IN OUT UTL_FILE.FILE_TYPE);

パラメータ

表11-4 FCLOSEプロシージャのパラメータ

パラメータ 説明

file

FOPENまたはFOPEN_NCHARコールが戻すアクティブなファイル・ハンドル

例外

これらの例外については、例外を参照してください。 

INVALID_FILEHANDLE
WRITE_ERROR

FCLOSEの実行時に、まだ書き込んでいないデータがバッファに残っていると、ファイルのクローズ時にWRITE_ERRORを受け取る場合があります。

例

例を参照してください。

FCLOSE_ALLプロシージャ

このプロシージャは、セッションでオープンしているすべてのファイル・ハンドルをクローズします。これは、PL/SQLプログラムの例外終了後などの非常時のクリーンアップ・プロシージャとして役立ちます。

構文

UTL_FILE.FCLOSE_ALL;

使用上のノート

FCLOSE_ALLは、ユーザーが保持しているオープン・ファイル・ハンドルの状態は変更しません。つまり、FCLOSE_ALLコール後のファイル・ハンドルのIS_OPENテストでは、たとえファイルがすでにクローズしていてもTRUEが戻されます。FCLOSE_ALLの前にオープンされたファイルには、以降の読込み操作や書込み操作を行うことができません。

例外

例外を参照してください。 

WRITE_ERROR

FCOPYプロシージャ

このプロシージャは、ファイルの連続部分を新規に作成したファイルにコピーします。

デフォルトでは、start_lineパラメータとend_lineパラメータが省略されると、ファイル全体がコピーされます。ソース・ファイルは読取りモードでオープンします。宛先ファイルは書込みモードでオープンします。ソース・ファイルのコピー操作では、ファイルの一部を選択するために、開始および終了の行番号をオプションで指定できます。

構文

UTL_FILE.FCOPY (
   src_location    IN VARCHAR2,
   src_filename    IN VARCHAR2,
   dest_location   IN VARCHAR2,
   dest_filename   IN VARCHAR2,
  [start_line      IN BINARY_INTEGER DEFAULT 1,
   end_line        IN BINARY_INTEGER DEFAULT NULL]);

パラメータ

表11-5 FCOPYプロシージャのパラメータ

パラメータ 説明

src_location

ソース・ファイルのディレクトリ位置。

src_filename

コピー対象のソース・ファイル。

dest_location

宛先ファイルが作成される宛先ディレクトリ。

dest_filename

ソース・ファイルから作成された宛先ファイル。

start_line

コピー操作を開始する行の番号。

デフォルトは、最初の行の1です。

end_line

コピー操作を停止する行の番号。

デフォルトは、ファイルの最後を示すNULLです。

例外

例外を参照してください。 

INVALID_FILENAME
INVALID_PATH
INVALID_OPERATION
INVALID_OFFSET
READ_ERROR
WRITE_ERROR

FFLUSHプロシージャ

FFLUSHは、ファイル・ハンドルが示すファイルに、保留中のデータを物理的に書き込みます。

通常、ファイルに書き込むデータはバッファリングされます。FFLUSHプロシージャは、バッファリングされているデータを強制的にファイルに書き込みます。データは改行文字で終了する必要があります。

フラッシュは、まだオープンしているファイルを読み込む必要がある場合に役立ちます。たとえば、デバッグ・メッセージをファイルにフラッシュして、即時に読み込むことができます。

構文

UTL_FILE.FFLUSH (
   file  IN UTL_FILE.FILE_TYPE);

パラメータ

表11-6 FFLUSHプロシージャのパラメータ

パラメータ 説明

file

FOPENまたはFOPEN_NCHARコールが戻すアクティブなファイル・ハンドル

例外

例外を参照してください。 

INVALID_FILEHANDLE
INVALID_OPERATION
WRITE_ERROR

例

例を参照してください。

FGETATTRプロシージャ

このプロシージャは、ファイルの属性を読み取って返します。

構文

UTL_FILE.FGETATTR(
   location    IN VARCHAR2, 
   filename    IN VARCHAR2, 
   fexists     OUT BOOLEAN, 
   file_length OUT NUMBER, 
   block_size   OUT BINARY_INTEGER);

パラメータ

表11-7 FGETATTRプロシージャのパラメータ

パラメータ 説明

location

ソース・ファイルの位置

filename

検証されるファイルの名前。

fexists

ファイルが存在するかどうかを示すBOOLEAN

file_length

バイト単位でのファイルの長さ、またはファイルが存在しない場合はNULL

block_size

バイト単位でのファイル・システムのブロック・サイズ、またはファイルが存在しない場合はNULL

例外

例外を参照してください。 

INVALID_PATH
INVALID_FILENAME
INVALID_OPERATION
READ_ERROR
ACCESS_DENIED

FGETPOSファンクション

このファンクションは、ファイル内の現行の相対オフセット位置をバイト数で戻します。

構文

UTL_FILE.FGETPOS (
   file   IN utl_file.file_type)
 RETURN BINARY_INTEGER;

パラメータ

表11-8 FGETPOSファンクションのパラメータ

パラメータ 説明

file

FOPENまたはFOPEN_NCHARコールが戻すアクティブなファイル・ハンドル

戻り値

オープン・ファイルのバイト単位での相対的なオフセット位置、またはファイルの先頭の場合は0

例外

例外を参照してください。 

INVALID_FILEHANDLE
INVALID_OPERATION
READ_ERROR

ファイルがオープンしていない場合は、INVALID_FILEHANDLE例外が発生します。ファイルがバイト・モード操作用にオープンしていた場合は、INVALID_OPERATION例外が発生します。

FOPENファンクション

このファンクションは、ファイルをオープンします。最大行サイズを指定でき、最大50ファイルまで同時にオープンできます。

FOPEN_NCHARファンクションも参照してください。

構文

UTL_FILE.FOPEN (
   location     IN VARCHAR2,
   filename     IN VARCHAR2,
   open_mode    IN VARCHAR2,
   max_linesize IN BINARY_INTEGER DEFAULT 1024) 
  RETURN utl_file.file_type;

パラメータ

表11-9 FOPENファンクションのパラメータ

パラメータ 説明

location

ファイルのディレクトリ位置。

filename

拡張子(ファイル・タイプ)も含めたファイル名で、ディレクトリ・パスはありません

ディレクトリ・パスがファイル名の一部として指定される場合も、FOPENに無視されます。LinuxまたはUNIXでは、ファイル名の末尾にスラッシュ(/)を指定できません。

open_mode

ファイルがオープンしたモード

  • r - テキストの読込み

  • w - テキストの書込み

  • a - テキストの追加

  • rb - バイトの読込み

  • wb - バイトの書込み

  • ab - バイトの追加

open_modeに'a'や'ab'を指定してファイルをオープンしようとしたときに、そのファイルが存在しない場合、ファイルはWRITEモードで作成されます。

max_linesize

改行文字を含むこのファイルの1行当たりの最大文字数

最小値は1、最大値は32767です。指定しない場合は、デフォルト値の1024が設定されます。

戻り値

そのファイルを操作する後続プロシージャすべてに渡す必要のあるファイル・ハンドル

ファイル・ハンドルの特定の内容は、UTL_FILEパッケージ専用であり、UTL_FILEのユーザーは、個々のコンポーネントの参照または変更を行わないでください。

使用上のノート

ファイルの場所とファイル名の各パラメータは、別々の文字列としてFOPENファンクションに指定されるため、ファイルの場所は、utl_file_tempディレクトリと照合してチェックできます。ファイルの場所と名前は、システム上の有効なファイル名である必要があり、ディレクトリはアクセス可能である必要があります。utl_file_tempのサブディレクトリにはアクセスできません。

例外

例外を参照してください。 

INVALID_PATH
INVALID_MODE
INVALID_OPERATION
INVALID_MAXLINESIZE

例

例を参照してください。

FOPEN_NCHARファンクション

このファンクションは、指定した最大行サイズで入力用または出力用ファイルを各国語文字セット・モードでオープンします。最大50ファイルまで同時にオープンできます。このファンクションを使用すると、データベース文字セットではなくUnicodeでテキスト・ファイルの読込みまたは書込みを実行できます。

NVARCHAR2のバッファの内容が(データベースの各国語文字セットによっては)AL16UTF16またはUTF-8の可能性がある場合でも、ファイルの内容は常にUTF-8で読取りおよび書込みされます。UTL_FILEは、必要に応じてUTF-8とAL16UTF16の間で変換を行います。

FOPENファンクションも参照してください。

構文

UTL_FILE.FOPEN_NCHAR (
   location     IN VARCHAR2,
   filename     IN VARCHAR2,
   open_mode    IN VARCHAR2,
   max_linesize IN BINARY_INTEGER DEFAULT 1024) 
RETURN utl_file.file_type;

パラメータ

表11-10 FOPEN_NCHARファンクションのパラメータ

パラメータ 説明

location

ファイルのディレクトリ位置。

filename

拡張子も含めたファイル名

open_mode

ファイルをオープンするモード: r、w、a、rb、wbまたはab(FOPENの説明を参照)

max_linesize

改行文字を含むこのファイルの1行当たりの最大文字数

最小値は1、最大値は32767です。指定しない場合は、デフォルト値の1024が設定されます。

戻り値

そのファイルを操作する後続プロシージャすべてに渡す必要のあるファイル・ハンドル

ファイル・ハンドルの特定の内容は、UTL_FILEパッケージ専用であり、UTL_FILEのユーザーは、個々のコンポーネントの参照または変更を行わないでください。

例外

例外を参照してください。 

INVALID_PATH
INVALID_MODE
INVALID_OPERATION
INVALID_MAXLINESIZE

FREMOVEプロシージャ

このプロシージャは、十分な権限がある場合にファイルを削除します。

構文

UTL_FILE.FREMOVE (
   location IN VARCHAR2,
   filename IN VARCHAR2);

パラメータ

表11-11 FREMOVEプロシージャのパラメータ

パラメータ 説明

location

ファイルのディレクトリ位置

filename

削除されるファイルの名前。

使用上のノート

このプロシージャでは、ファイルを削除する前に権限の有無を検証しません。ファイルとディレクトリに対するアクセス権限は、オペレーティング・システムによって検証されます。

例外

例外を参照してください。 

INVALID_PATH
INVALID_FILENAME
INVALID_OPERATION
ACCESS_DENIED
DELETE_FAILED

FRENAMEプロシージャ

このプロシージャは、既存のファイルの名前を変更します。

構文

UTL_FILE.FRENAME (
   src_location  IN VARCHAR2,
   src_filename  IN VARCHAR2, 
   dest_location IN VARCHAR2,
   dest_filename IN VARCHAR2,
   overwrite     IN BOOLEAN DEFAULT FALSE);

パラメータ

表11-12 FRENAMEプロシージャのパラメータ

パラメータ 説明

src_location

ソース・ファイルのディレクトリ位置。

src_filename

名前変更対象のソース・ファイル。

dest_location

宛先ファイルの宛先ディレクトリ

dest_filename

ファイルの新しい名前。

overwrite

宛先ディレクトリ内の既存のファイルの上書きを許可するかどうか(デフォルト: FALSE)

使用上のノート

ソース・ディレクトリと宛先ディレクトリの両方に対するアクセス権限の付与が必要です。

例外

例外を参照してください。 

INVALID_PATH
INVALID_FILENAME
RENAME_FAILED
ACCESS_DENIED

FSEEKプロシージャ

このプロシージャは、指定したバイトの数だけ、ファイル内でポインタを前方または後方に調整します。

構文

UTL_FILE.FSEEK (
   file            IN OUT utl_file.file_type,
   absolute_offset IN     BINARY_INTEGER DEFAULT NULL,
   relative_offset IN     BINARY_INTEGER DEFAULT NULL);

パラメータ

表11-13 FSEEKプロシージャのパラメータ

パラメータ 説明

file

FOPENまたはFOPEN_NCHARコールが戻すアクティブなファイル・ハンドル

absolute_offset

検索先のバイト単位での絶対位置(デフォルト=NULL)

relative_offset

前方または後方に検索するバイト数

前方に検索する場合は正の整数、後方に検索する場合は負の整数、現在の位置の場合は0(ゼロ)。デフォルトはNULLです。

使用上のノート

  • FSEEKを使用すると、最初にファイルのクローズと再オープンを行わずに、ファイル内の前の行を読み込むことができます。ナビゲートするバイト数を把握しておく必要があります。

  • 指定されたバイト数に至る前にファイルの先頭まで到達した場合、ファイル・ポインタはファイルの先頭に置かれます。

例外

例外を参照してください。 

INVALID_FILEHANDLE
INVALID_OPERATION
READ_ERROR
INVALID_OFFSET

ファイルがバイト・モード操作用にオープンしていた場合は、INVALID_OPERATION例外が発生します。指定されたバイト数に至る前にファイルの終わりに達した場合は、INVALID_OFFSETエラーが発生します。

GET_LINEプロシージャ

このプロシージャは、ファイル・ハンドルが示すオープン・ファイルからテキストを読み込んで、出力バッファ・パラメータに配置します。

テキストは、ファイルまたはlenパラメータの最後まで読み込まれますが、行の終了記号は含まれません。FOPENに指定されているmax_linesizeを超えることはできません。

構文

UTL_FILE.GET_LINE (
   file        IN  UTL_FILE.FILE_TYPE,
   buffer      OUT VARCHAR2,
   len         IN  BINARY_INTEGER DEFAULT NULL);

パラメータ

表11-14 GET_LINEプロシージャのパラメータ

パラメータ 説明

file

FOPENコールが戻すアクティブなファイル・ハンドル。

buffer

ファイルから読み込まれた行を受け取るデータ・バッファ。

len

ファイルから読み込むバイト数

NULL(デフォルト)を指定すると、FOPENのmax_linesizeの値が設定されます。

使用上のノート

  • 行終了記号の文字はバッファに読み込まれないため、ブランク行を読み込むと空の文字列が戻されます。

  • bufferパラメータの最大サイズは、より小さいサイズをFOPENに指定しないかぎり、32767バイトです。

  • 指定しない場合は、デフォルト値の1024が設定されます。GET_LINE_NCHARプロシージャも参照してください。

例外

例外を参照してください。 

INVALID_FILEHANDLE
INVALID_OPERATION
READ_ERROR
CHARSETMISMATCH
NO_DATA_FOUND
VALUE_ERROR

ファイルが読取りモード用(モードr)にオープンしていない場合、またはバイト・モード操作用にオープンしていた場合は、INVALID_OPERATIONがスローされます。FOPENでなくFOPEN_NCHARを使用してファイルをオープンした場合は、CHARSETMISMATCHがスローされます。ファイルの終わりに到達したためにテキストが読み込まれなかった場合は、NO_DATA_FOUNDがスローされます。行がバッファに格納されない場合は、VALUE_ERRORがスローされます。(NO_DATA_FOUNDおよびVALUE_ERRORは、事前定義済のPL/SQL例外です。)

例

例を参照してください。

GET_LINE_NCHARプロシージャ

このプロシージャは、ファイル・ハンドルが示すオープン・ファイルからテキストを読み込んで、出力バッファ・パラメータに配置します。このファンクションを使用すると、データベース文字セットではなくUnicodeでテキスト・ファイルの読込みを実行できます。

ファイルは、各国語文字セット・モードでオープンされ、UTF-8文字セットにエンコードされます。想定されるバッファのデータ・タイプは、NVARCHAR2です。NCHAR、VARCHAR2など、その他のデータ型の変数が指定された場合、テキストの読取りの後で、PL/SQLでNVARCHAR2からの標準の暗黙的な変換が実行されます。

GET_LINEプロシージャも参照してください。

構文

UTL_FILE.GET_LINE_NCHAR (
   file        IN  UTL_FILE.FILE_TYPE,
   buffer      OUT NVARCHAR2,
   len         IN  BINARY_INTEGER DEFAULT NULL);

パラメータ

表11-15 GET_LINE_NCHARプロシージャのパラメータ

パラメータ 説明

file

FOPEN_NCHARコールが戻すアクティブなファイル・ハンドル

このファイルは読込み用(モードr)にオープンされる必要があります。

buffer

ファイルから読み込まれた行を受け取るデータ・バッファ。

len

ファイルから読み込むバイト数

NULL(デフォルト)を指定すると、FOPEN_NCHARのmax_linesizeの値が設定されます。

例外

例外を参照してください。 

INVALID_FILEHANDLE
INVALID_OPERATION
READ_ERROR
CHARSETMISMATCH
NO_DATA_FOUND
VALUE_ERROR

ファイルが読取りモード用(モードr)にオープンしていない場合、またはバイト・モード操作用にオープンしていた場合は、INVALID_OPERATIONがスローされます。ファイルの終わりに到達したためにテキストが読み込まれなかった場合は、NO_DATA_FOUNDがスローされます。行がバッファに格納されない場合は、VALUE_ERRORがスローされます。FOPEN_NCHARでなくFOPENでファイルをオープンした場合は、CHARSETMISMATCHがスローされます。(NO_DATA_FOUNDおよびVALUE_ERRORは、事前定義済のPL/SQL例外です。)

GET_RAWプロシージャ

このプロシージャは、RAW文字列値をファイルから読み込み、読み込んだバイトの数だけ、ファイルのポインタを前方に調整します。行終了記号は無視します。

構文

UTL_FILE.GET_RAW (
   file    IN  utl_file.file_type, 
   buffer  OUT NOCOPY RAW, 
   len     IN  BINARY_INTEGER DEFAULT NULL);

パラメータ

表11-16 GET_RAWファンクションのパラメータ

パラメータ 説明

file

FOPENまたはFOPEN_NCHARコールが戻すアクティブなファイル・ハンドル

buffer

RAWデータ

len

ファイルから読み込むバイト数

NULL(デフォルト)の場合、lenはRAWの最大長とみなされます。

例外

例外を参照してください。 

INVALID_FILEHANDLE
INVALID_OPERATION
READ_ERROR
LENGTH_MISMATCH
NO_DATA_FOUND

(NO_DATA_FOUNDは、事前定義済のPL/SQL例外です。)

例

例を参照してください。

IS_OPENファンクション

このファンクションは、オープン・ファイルをファイル・ハンドルが識別しているかどうかをテストします。これは、ファイル・ハンドルが、オープン状態でクローズしていないファイルを示しているかどうかを通知するのみです。これは、エラーなしでファイルを使用できることを保証するものではありません。

構文

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

パラメータ

表11-17 IS_OPENファンクションのパラメータ

パラメータ 説明

file

FOPENまたはFOPEN_NCHARコールが戻すアクティブなファイル・ハンドル

戻り値

ファイルがオープンしている場合はTRUE、そうでない場合はFALSE

例外

例外を参照してください。 

INVALID_FILEHANDLE

NEW_LINEプロシージャ

このプロシージャは、入力ファイル・ハンドルが示すファイルに、1つ以上の行終了記号を書き込みます。行終了記号はプラットフォーム固有の文字や文字列であるため、このプロシージャはPUTとは異なります。

構文

UTL_FILE.NEW_LINE (
   file     IN UTL_FILE.FILE_TYPE,
   lines    IN BINARY_INTEGER := 1);

パラメータ

表11-18 NEW_LINEプロシージャのパラメータ

パラメータ 説明

file

FOPENまたはFOPEN_NCHARコールが戻すアクティブなファイル・ハンドル

lines

ファイルに書き込む行終了記号の数。

例外

例外を参照してください。 

INVALID_FILEHANDLE
INVALID_OPERATION
WRITE_ERROR

PUTプロシージャ

PUTプロシージャは、ファイル・ハンドルが示すオープン・ファイルに、バッファ・パラメータ内に格納されているテキスト文字列を書き込みます。

このファイルは書込み操作用にオープンされる必要があります。PUTは、行終了記号を追加しません。行の終了にはNEW_LINEを使用するか、またはPUT_LINEを使用して行終了記号付きの完全な1行を書き込んでください。PUT_NCHARプロシージャも参照してください。

構文

UTL_FILE.PUT (
   file      IN UTL_FILE.FILE_TYPE,
   buffer    IN VARCHAR2);

パラメータ

表11-19 PUTプロシージャのパラメータ

パラメータ 説明

file

FOPEN_NCHARコールが戻すアクティブなファイル・ハンドル

このファイルは書込み用(モードw)にオープンされる必要があります。

buffer

ファイルに書き込むテキストを含んだバッファ

使用上のノート

bufferパラメータの最大サイズは、より小さいサイズをFOPENに指定しないかぎり、32767バイトです。指定しない場合は、デフォルト値の1024が設定されます。連続したPUTコールの全合計は、途中でバッファ・フラッシュをしないかぎり、32767を超えません。

例外

例外を参照してください。 

INVALID_FILEHANDLE
INVALID_OPERATION
WRITE_ERROR
CHARSETMISMATCH

モードwまたはa(書込みまたは追加)を使用してファイルをオープンしていない場合は、INVALID_OPERATIONがスローされます。FOPENでなくFOPEN_NCHARを使用してファイルをオープンした場合は、CHARSETMISMATCHがスローされます。

PUT_LINEプロシージャ

このプロシージャは、ファイル・ハンドルが示すオープン・ファイルに、バッファ・パラメータ内に格納されているテキスト文字列を書き込みます。

このファイルは書込み操作用にオープンされる必要があります。PUT_LINEは、プラットフォーム固有の行終了文字または文字列で行を終了します。PUT_LINE_NCHARプロシージャも参照してください。

構文

UTL_FILE.PUT_LINE (
   file      IN UTL_FILE.FILE_TYPE,
   buffer    IN VARCHAR2,
   autoflush IN BOOLEAN DEFAULT FALSE);

パラメータ

表11-20 PUT_LINEプロシージャのパラメータ

パラメータ 説明

file

FOPENコールが戻すアクティブなファイル・ハンドル。

buffer

ファイルに書き込む行を含んだテキスト・バッファ。

autoflush

書込み後にバッファをファイル・システムにフラッシュするためのフラグ

使用上のノート

bufferパラメータの最大サイズは、より小さいサイズをFOPENに指定しないかぎり、32767バイトです。指定しない場合は、デフォルト値の1024が設定されます。連続したPUTコールの全合計は、途中でバッファ・フラッシュをしないかぎり、32767を超えません。

例外

例外を参照してください。 

INVALID_FILEHANDLE
INVALID_OPERATION
WRITE_ERROR
CHARSETMISMATCH

ファイルがバイト・モード操作用にオープンしている場合は、INVALID_OPERATIONがスローされます。FOPENでなくFOPEN_NCHARを使用してファイルをオープンした場合は、CHARSETMISMATCHがスローされます。

PUT_LINE_NCHARプロシージャ

このプロシージャは、ファイル・ハンドルが示すオープン・ファイルに、バッファ・パラメータ内に格納されているテキスト文字列を書き込みます。

このファンクションを使用すると、データベース文字セットではなくUnicodeでテキスト・ファイルの書込みを実行できます。このプロシージャは、書き込まれたテキストに行セパレータが追加されることを除いて、PUT_NCHARプロシージャと同じです。PUT_LINEプロシージャも参照してください。

構文

UTL_FILE.PUT_LINE_NCHAR (
   file    IN UTL_FILE.FILE_TYPE,
   buffer  IN NVARCHAR2);

パラメータ

表11-21 PUT_LINE_NCHARプロシージャのパラメータ

パラメータ 説明

file

FOPEN_NCHARコールが戻すアクティブなファイル・ハンドル

このファイルは書込み用(モードw)にオープンされる必要があります。

buffer

ファイルに書き込む行を含んだテキスト・バッファ。

使用上のノート

bufferパラメータの最大サイズは、より小さいサイズをFOPENに指定しないかぎり、32767バイトです。指定しない場合は、デフォルト値の1024が設定されます。連続したPUTコールの全合計は、途中でバッファ・フラッシュをしないかぎり、32767を超えません。

例外

例外を参照してください。 

INVALID_FILEHANDLE
INVALID_OPERATION
WRITE_ERROR
CHARSETMISMATCH

ファイルがバイト・モード操作用にオープンしている場合は、INVALID_OPERATIONがスローされます。FOPEN_NCHARでなくFOPENを使用してファイルをオープンした場合は、CHARSETMISMATCHがスローされます。

PUT_NCHARプロシージャ

このプロシージャは、ファイル・ハンドルが示すオープン・ファイルに、バッファ・パラメータ内に格納されているテキスト文字列を書き込みます。

このファンクションを使用すると、データベース文字セットではなくUnicodeでテキスト・ファイルの書込みを実行できます。このファイルは、各国語文字セット・モードでオープンされる必要があります。テキスト文字列は、UTF-8文字セットで書き込まれます。想定されるバッファのデータ・タイプは、NVARCHAR2です。その他のデータ型の変数が指定された場合、テキストの書込みの前に、PL/SQLでNVARCHAR2への暗黙的な変換が実行されます。

PUTプロシージャも参照してください。

構文

UTL_FILE.PUT_NCHAR (
   file      IN UTL_FILE.FILE_TYPE,
   buffer    IN NVARCHAR2);

パラメータ

表11-22 PUT_NCHARプロシージャのパラメータ

パラメータ 説明

file

FOPEN_NCHARコールが戻すアクティブなファイル・ハンドル

buffer

ファイルに書き込むテキストを含んだバッファ

使用上のノート

bufferパラメータの最大サイズは、より小さいサイズをFOPENに指定しないかぎり、32767バイトです。指定しない場合は、デフォルト値の1024が設定されます。連続したPUTコールの全合計は、途中でバッファ・フラッシュをしないかぎり、32767を超えません。

例外

例外を参照してください。 

INVALID_FILEHANDLE
INVALID_OPERATION
WRITE_ERROR
CHARSETMISMATCH

モードwまたはa(書込みまたは追加)を使用してファイルをオープンしていない場合は、INVALID_OPERATIONがスローされます。FOPEN_NCHARでなくFOPENでファイルをオープンした場合は、CHARSETMISMATCHがスローされます。

PUT_RAWプロシージャ

このプロシージャは、RAWデータ値を入力として受け入れ、出力バッファに書き込みます。

構文

UTL_FILE.PUT_RAW (
   file       IN utl_file.file_type,
   buffer     IN RAW, 
   autoflush  IN BOOLEAN DEFAULT FALSE);

パラメータ

表11-23 PUT_RAWプロシージャのパラメータ

パラメータ 説明

file

FOPENまたはFOPEN_NCHARコールが戻すアクティブなファイル・ハンドル

buffer

バッファに書き込まれたRAWデータ。

autoflush

出力バッファに値を書き込んだ後でフラッシュを実行するフラグ(デフォルト: FALSEです)

使用上のノート

autoflushにTRUEを設定することで、バッファの自動フラッシュを要求できます。

bufferパラメータの最大サイズは、より小さいサイズをFOPENに指定しないかぎり、32767バイトです。指定しない場合は、デフォルト値の1024が設定されます。連続したPUTコールの全合計は、途中でバッファ・フラッシュをしないかぎり、32767を超えません。

例外

例外を参照してください。 

INVALID_FILEHANDLE
INVALID_OPERATION
WRITE_ERROR

PUTFプロシージャ

このプロシージャは、書式付きのPUTプロシージャです。これは、制限付きのprintf()のように動作します。

PUTF_NCHARプロシージャも参照してください。

構文

UTL_FILE.PUTF (
   file    IN UTL_FILE.FILE_TYPE,
   format  IN VARCHAR2,
   [arg1   IN VARCHAR2  DEFAULT NULL,
   . . .  
   arg5    IN VARCHAR2  DEFAULT NULL]);

パラメータ

表11-24 PUTFプロシージャのパラメータ

パラメータ 説明

file

FOPENコールが戻すアクティブなファイル・ハンドル。

format

テキストや書式文字\nと%sを含むことができる書式文字列

arg1..arg5

1から5個までのオプションの引数文字列

引数文字列は、書式文字列内の%s書式指定文字に、順序正しく置き換えられます。引数より多い書式指定文字が書式パラメータ文字列内にある場合は、引数のない各%sは空の文字列に置き換えられます。

使用上のノート

書式文字列には任意のテキストを指定できますが、文字列%sと\nには特別な意味があります。

文字列 意味

%s

この文字列を引数リスト内の次の引数の文字列値に置き換えます。

\n

適切なプラットフォーム固有の行終了記号に置き換えます。

例外

例外を参照してください。 

INVALID_FILEHANDLE
INVALID_OPERATION
WRITE_ERROR
CHARSETMISMATCH

ファイルがバイト・モード操作用にオープンしている場合は、INVALID_OPERATIONがスローされます。FOPENでなくFOPEN_NCHARを使用してファイルをオープンした場合は、CHARSETMISMATCHがスローされます。

例

例を参照してください。

PUTF_NCHARプロシージャ

PUTF_NCHARを使用すると、データベース文字セットではなくUnicodeでテキスト・ファイルの書込みを実行できます。

このプロシージャは、PUT_NCHARプロシージャの書式付きのバージョンです。

これは、書式要素\nおよび%sを含む書式文字列を受け入れ、書式文字列内の%sの連続出現を最大で5つの引数に置き換えることができます。書式文字列および引数に想定されるデータ・タイプは、NVARCHAR2です。

別のデータ型の変数が指定されていると、テキストの書式設定前に、PL/SQLでNVARCHAR2への暗黙的な変換が実行されます。書式化されたテキストは、ファイル・ハンドルが示すファイルにUTF-8文字セットで書き込まれます。このファイルは、各国語文字セット・モードでオープンされる必要があります。

構文

UTL_FILE.PUTF_NCHAR (
   file    IN UTL_FILE.FILE_TYPE,
   format  IN NVARCHAR2,
   [arg1   IN NVARCHAR2  DEFAULT NULL,
   . . .  
   arg5    IN NVARCHAR2  DEFAULT NULL]);

パラメータ

表11-25 PUTF_NCHARプロシージャのパラメータ

パラメータ 説明

file

FOPEN_NCHARコールが戻すアクティブなファイル・ハンドル

このファイルは読込み用(モードr)にオープンされる必要があります。

format

テキストや書式文字\nと%sを含むことができる書式文字列

arg1..arg5

1から5個までのオプションの引数文字列

引数文字列は、書式文字列内の%s書式文字に、順序正しく置き換えられます。引数より多い書式文字が書式文字列内にある場合は、引数のない各%sは空の文字列に置き換えられます。

使用上のノート

bufferパラメータの最大サイズは、より小さいサイズをFOPENに指定しないかぎり、32767バイトです。指定しない場合は、デフォルト値の1024が設定されます。連続したPUTコールの全合計は、途中でバッファ・フラッシュをしないかぎり、32767を超えません。

例外

例外を参照してください。 

INVALID_FILEHANDLE
INVALID_OPERATION
WRITE_ERROR
CHARSETMISMATCH

ファイルがバイト・モード操作用にオープンしている場合は、INVALID_OPERATIONがスローされます。FOPEN_NCHARでなくFOPENでファイルをオープンした場合は、CHARSETMISMATCHがスローされます。