ヘッダーをスキップ
Oracle® Database PL/SQLパッケージおよびタイプ・リファレンス
11g リリース2(11.2)
B56262-06
  目次へ移動
目次		 索引へ移動
索引
前
前 		 次
次		  

224 UTL_FILE

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

この章では、次の項目について説明します。

UTL_FILEの使用方法

セキュリティ・モデル

ユーザーがUTL_FILEを使用してアクセスできるファイルおよびディレクトリのセットは、ファクタおよびデータベース・パラメータの数によって制御されます。最初にアクセスできるのは、ユーザーが権限を付与されているディレクトリ・オブジェクトのセットです。ディレクトリ・オブジェクトの性質については、『Oracle Database SQL言語リファレンス』を参照してください。

ユーザーがディレクトリ・オブジェクトUSER_DIRに対してREADとWRITEの両方のアクセス権を持つ場合、USER_DIRで記述されているオペレーティング・システム・ディレクトリにあるファイルを開くことはできますが、このディレクトリのサブディレクトリや親ディレクトリにあるファイルを開くことはできません。

最後に、クライアント側(テキストI/O)とサーバー側の両方の実装について、オペレーティング・システム・ファイルに対するアクセス権限のチェックが行われます。

UTL_FILEでは、クライアント側とサーバー側の両方からのファイル・アクセスが提供されています。UTL_FILEをサーバー上で実行すると、そのサーバーからアクセスできるすべてのオペレーティング・システム・ファイルにアクセスできます。クライアント側では、Formsアプリケーションの場合と同様に、UTL_FILEによって、クライアントからアクセスできるオペレーティング・システム・ファイルへのアクセスが提供されます。

これまではUTL_FILEファンクションのアクセス可能なディレクトリは、UTL_FILE_DIRパラメータを使用して初期化ファイルに指定してきました。ただし、UTL_FILE_DIRへのアクセスはお薦めしません。かわりにディレクトリ・オブジェクト機能を使用することをお薦めします。この機能によって、UTL_FILE_DIRが置き換えられます。UTL_FILEのアプリケーション管理者による柔軟できめ細かい制御を可能にするディレクトリ・オブジェクトは、動的に(データベースを停止しないで)メンテナンスでき、Oracleの他のツールとの一貫性を保持しています。CREATE ANY DIRECTORY権限は、SYSおよびSYSTEMに対してのみデフォルトで付与されます。


注意:

ディレクトリのアクセス検証には、UTL_FILE_DIRではなく、CREATE DIRECTORY機能を使用してください。

ハード・リンクまたはシンボリック・リンクのいずれもサポートされていないことに注意してください。

UNIXシステムでは、FOPENファンクションで作成したファイルにはそのファイルの所有者、つまりインスタンスを実行するシャドウ・プロセスの所有者がいます。通常、この所有者はORACLEです。FOPENを使用して作成されたファイルは、UTL_FILEサブプログラムを使用する書込みと読込みが常に可能です。ただし、権限のないオペレーティング・システムのユーザーがPL/SQLの外部でこれらのファイルを読む必要がある場合は、システム管理者からのアクセス権の入手が必要になることがあります。


注意:

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

使用上の注意

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

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

  • GET_LINEのlenパラメータ

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

  • UTL_FILE.FOPENによって指定されたmax_linesizeパラメータ

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

UTL_FILE.GET_RAWは行終了記号を無視します。

UTL_FILEでは、UTL_FILE.FOPENによってテキスト・モードでオープンされるファイルは、データベースのキャラクタ・セットにエンコードされます。UTL_FILE.FOPEN_NCHARによってテキスト・モードでオープンされるファイルは、UTF8キャラクタ・セットにエンコードされます。オープンされたファイルが目的のキャラクタ・セットにエンコードされない場合、ファイルの読取り試行の結果は不定です。1つのキャラクタ・セットにエンコードされたデータが読み取られ、そのデータを別のキャラクタ・セットにエンコードするようにグローバリゼーション・サポートが命じられた(NLS_LANGなどを使用して)場合、結果は不定です。NLS_LANGを設定する場合は、データベースのキャラクタ・セットと同じものにする必要があります。

ルールおよび制限

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

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


注意:

UTL_FILEパッケージは、Oracle Procedure Builderが提供しているクライアント側のTEXT_IOパッケージと類似しています。サーバー・インプリメンテーションに対する制約事項には、UTL_FILEとTEXT_IOの間である程度のAPIに差異が必要です。PL/SQLのファイルI/Oでは、PL/SQL例外を使用して、ユーザーにエラーが戻されます。

例外

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

例外名 説明

INVALID_PATH

ファイルの場所が無効です。

INVALID_MODE

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

INVALID_FILEHANDLE

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

INVALID_OPERATION

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

READ_ERROR

宛先のバッファが小さすぎるか、または読取り操作中にオペレーティング・システムのエラーが発生しました。

WRITE_ERROR

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

INTERNAL_ERROR

PL/SQL内の未指定エラー。

CHARSETMISMATCH

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

FILE_OPEN

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

INVALID_MAXLINESIZE

FOPEN()のMAX_LINESIZE値が無効です。1から32767の範囲内の値にしてください。

INVALID_FILENAME

ファイル名パラメータが無効です。

ACCESS_DENIED

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

INVALID_OFFSET

INVALID_OFFSET例外の原因には次のようなものがあります。

  • ABSOLUTE_OFFSET = NULLとRELATIVE_OFFSET = NULLが同時に発生

  • ABSOLUTE_OFFSET < 0

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

DELETE_FAILED

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

RENAME_FAILED

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

UTL_FILEにおけるプロシージャでは、NO_DATA_FOUNDまたはVALUE_ERRORのような事前定義済のPL/SQL例外が発生することもあります。

例

例1


注意:

ここに示す例はUNIX固有のものです。

次の文があるとします。

SQL> CREATE DIRECTORY log_dir AS '/appl/gl/log'; 
SQL> GRANT READ ON DIRECTORY log_dir TO DBA; 
SQL> GRANT WRITE ON DIRECTORY log_dir TO DBA; 

SQL> CREATE DIRECTORY USER_DIR AS '/appl/gl/user''; 
SQL> GRANT READ ON DIRECTORY USER_DIR TO PUBLIC; 
SQL> GRANT WRITE ON DIRECTORY USER_DIR TO PUBLIC;

有効でアクセス可能なファイルの場所とファイル名は、次のとおりです。

ファイルの場所 ファイル名 読込みおよび書込み
/appl/gl/log L12345.log DBA権限を持つユーザー
/appl/gl/user u12345.tmp すべてのユーザー

次のファイルの場所とファイル名は無効です。

ファイルの場所 ファイル名 無効の理由
/appl/gl/log/backup L12345.log #サブディレクトリにアクセスできません。
/APPL/gl/log L12345.log #ディレクトリの文字列は、O/Sで要求されている大/小文字区別ルールに従う必要があります。
/appl/gl/log backup/L1234.log #ファイル名にディレクトリ・パスの一部が含まれていない可能性があります。
/user/tmp L12345.log #対応するCREATE DIRECTORYコマンドが発行されていません。

例2

DECLARE 
  V1 VARCHAR2(32767); 
  F1 UTL_FILE.FILE_TYPE; 
BEGIN 
  -- In this example MAX_LINESIZE is less than GET_LINE's length request 
  -- so the number of bytes returned will be 256 or less if a line terminator is seen. 
  F1 := UTL_FILE.FOPEN('USER_DIR','u12345.tmp','R',256); 
  UTL_FILE.GET_LINE(F1,V1,32767); 
  UTL_FILE.FCLOSE(F1); 

  -- In this example, FOPEN's MAX_LINESIZE is NULL and defaults to 1024, 
  -- so the number of bytes returned will be 1024 or less if a line terminator is seen. 
  F1 := UTL_FILE.FOPEN('USER_DIR','u12345.tmp','R'); 
  UTL_FILE.GET_LINE(F1,V1,32767); 
  UTL_FILE.FCLOSE(F1); 

  -- In this example, GET_LINE doesn't specify a number of bytes, so it defaults to 
  -- the same value as FOPEN's MAX_LINESIZE which is NULL in this case and defaults to 1024. 
  -- So the number of bytes returned will be 1024 or less if a line terminator is seen. 
  F1 := UTL_FILE.FOPEN('USER_DIR','u12345.tmp','R'); 
  UTL_FILE.GET_LINE(F1,V1); 
  UTL_FILE.FCLOSE(F1); 
END;

データ構造

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

レコード・タイプ

FILETYPEレコード・タイプ

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

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

フィールド

表224-2 FILE_TYPEのフィールド

フィールド 説明

id

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

datatype

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

byte_mode

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


注意:

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

UTL_FILEサブプログラムの要約

表224-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つ以上のOS固有の行終了記号をファイルに書き込みます。

PUTプロシージャ

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

PUT_LINEプロシージャ

ファイルに1行書き込み、それによってOS固有の行終了記号を1つ追加します。

PUT_LINE_NCHARプロシージャ

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

PUT_NCHARプロシージャ

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

PUTFプロシージャ

書式付きのPUTプロシージャです。

PUTF_NCHARプロシージャ

書式付きのPUT_NCHARプロシージャ。ファイルにUnicode文字列を1つ、書式付きで書き込みます。

PUT_RAWプロシージャ

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

FCLOSEプロシージャ

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

構文

UTL_FILE.FCLOSE (
   file IN OUT FILE_TYPE);

パラメータ

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

パラメータ 説明

file

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

使用上の注意

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

例外

WRITE_ERROR
INVALID_FILEHANDLE

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);

パラメータ

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

パラメータ 説明

src_location

ソース・ファイルのディレクトリ位置。ALL_DIRECTORIESビューのDIRECTORY_NAME(大/小文字が区別されます)。

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 FILE_TYPE);

パラメータ

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

パラメータ 説明

file

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

例外

INVALID_FILENAME

INVALID_MAXLINESIZE

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);

パラメータ

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

パラメータ 説明

location

ソース・ファイルのディレクトリ位置。ALL_DIRECTORIESビューのDIRECTORY_NAME(大/小文字が区別されます)。

filename

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

fexists

ファイルが存在するかどうかを示すブール値。

file_length

ファイルの長さ(バイト単位)。ファイルが存在しない場合はNULLです。

block_size

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

例外

INVALID_PATH

INVALID_FILENAME

INVALID_OPERATION

READ_ERROR

ACCESS_DENIED

FGETPOSファンクション

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

構文

UTL_FILE.FGETPOS (
   file IN FILE_TYPE)
 RETURN PLS_INTEGER;

パラメータ

表224-8 FGETPOSのパラメータ

パラメータ 説明

file

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

戻り値

FGETPOSは、オープン・ファイルの相対的なオフセット位置をバイト数で戻します。ファイルがオープンしていない場合は、例外が発生します。ファイルの先頭では、0が戻されます。

例外

INVALID_FILEHANDLE

INVALID_OPERATION

READ_ERROR

使用上の注意

ファイルがバイト・モード操作用にオープンしている場合は、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 FILE_TYPE;

パラメータ

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

パラメータ 説明

location

ファイルのディレクトリ位置。この文字列はディレクトリのオブジェクト名で、大文字で指定する必要があります。UTL_FILEのユーザーがFOPENを実行するには、このディレクトリに対する読取り権限が付与されている必要があります。

filename

拡張子(ファイル・タイプ)も含めたファイル名で、ディレクトリ・パスはありません。ディレクトリ・パスがファイル名の一部として指定される場合も、FOPENに無視されます。UNIXでのファイル名は、/で終了できません。

open_mode

ファイルのオープン方法を指定します。次のモードがあります。

  • r -- テキストの読込み

  • w -- テキストの書込み

  • a -- テキストの追加

  • rb -- バイトの読込み

  • wb -- バイトの書込み

  • ab -- バイトの追加

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

max_linesize

改行文字を含むこのファイルの1行当たりの最大文字数(最小値は1、最大値は32767)。指定がない場合は、デフォルト値である1024が指定されます。

戻り値

FOPENは、そのファイルを操作する後続プロシージャすべてに渡す必要のあるファイル・ハンドルを戻します。ファイル・ハンドルの特定の内容は、UTL_FILEパッケージ専用であり、UTL_FILEのユーザーは、個々のコンポーネントの参照または変更を行わないでください。

表224-10 FOPENファンクションの戻り値

戻り値 説明

FILE_TYPE

オープン・ファイルのハンドル。

例外

INVALID_MAXILINESIZE

INVALID_MODE

INVALID_OPERATION

INVALID_PATH

INVALID_FILENAME

使用上の注意

ファイルの場所とファイル名の各パラメータは、引用符付きの文字列としてFOPENファンクションに指定する必要があります。これによってファイルの場所を、アクセス可能なディレクトリ・オブジェクトのALL_DIRECTORIESビューで指定されたアクセス可能なディレクトリのリストと照合してチェックできます。

FOPEN_NCHARファンクション

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

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

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

構文

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

パラメータ

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

パラメータ 説明

location

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

filename

ファイル名(拡張子を含む)。

open_mode

ファイルをオープンするモード(r、w、a、rb、wb、ab)

max_linesize

改行文字を含むこのファイルの1行当たりの最大文字数(最小値は1、最大値は32767)。

戻り値

FOPEN_NCHARは、そのファイルを操作する後続プロシージャすべてに渡す必要のあるファイル・ハンドルを戻します。ファイル・ハンドルの特定の内容は、UTL_FILEパッケージ専用であり、UTL_FILEのユーザーは、個々のコンポーネントの参照または変更を行わないでください。

表224-12 FOPEN_NCHARファンクションの戻り値

戻り値 説明

FILE_TYPE

オープン・ファイルのハンドル。

例外

INVALID_MAXILINESIZE

INVALID_MODE

INVALID_OPERATION

INVALID_PATH

FREMOVEプロシージャ

このプロシージャは、ユーザーに十分な権限があるという前提で、ディスク・ファイルを削除します。

構文

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

パラメータ

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

パラメータ 説明

location

ファイルのディレクトリ位置。ALL_DIRECTORIESビューのDIRECTORY_NAME(大/小文字が区別されます)。

filename

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

例外

ACCESS_DENIED

DELETE_FAILED

INVALID_FILENAME

INVALID_OPERATION

INVALID_PATH

使用上の注意

FREMOVEプロシージャでは、ファイルを削除する前に権限の有無を検証しません。ファイルとディレクトリに対するアクセス権限は、O/Sによって検証されます。障害時には、例外が戻されます。

FRENAMEプロシージャ

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

構文

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

パラメータ

表224-14 FRENAMEプロシージャのパラメータ

パラメータ 説明

src_location

ソース・ファイルのディレクトリ位置。ALL_DIRECTORIESビューのDIRECTORY_NAME(大/小文字が区別されます)。

src_filename

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

dest_location

宛先ファイルの宛先ディレクトリ。ALL_DIRECTORIESビューのDIRECTORY_NAME(大/小文字が区別されます)。

dest_filename

ファイルの新しい名前。

overwrite

デフォルトはFALSEです。ソース・ディレクトリと宛先ディレクトリの両方に対するアクセス権限の付与が必要です。宛先ディレクトリにファイルがある場合は、overwriteパラメータを使用して、そのファイルを上書きするかどうかを指定できます。デフォルトは、上書きしない場合のFALSEです。

例外

ACCESS_DENIED

INVALID_FILENAME

INVALID_PATH

RENAME_FAILED

FSEEKプロシージャ

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

構文

UTL_FILE.FSEEK (
   file             IN OUT  UTL_FILE.FILE_TYPE,
   absolute_offset  IN      PL_INTEGER DEFAULT NULL,
   relative_offset  IN      PLS_INTEGER DEFAULT NULL);

パラメータ

表224-15 FSEEKプロシージャのパラメータ

パラメータ 説明

file

ファイル・ハンドル。

absolute_offset

検索先の絶対位置。デフォルト=NULL。

relative_offset

前方または後方に検索するバイト数。正数=前方、負の整数=後方、0(ゼロ)=現在の位置、デフォルト=NULL。

例外

INVALID_FILEHANDLE

INVALID_OFFSET

INVALID_OPERATION

READ_ERROR

使用上の注意

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

  • relative_offsetを使用する場合、このプロシージャは前方検索(relative_offset > 0の場合)、または後方検索(relative_offset < 0の場合)を行い、指定されたrelative_offsetバイトの数のみファイルを検索します。

  • 指定されたバイト数に至る前にファイルの先頭まで到達した場合、ファイル・ポインタはファイルの先頭に置かれます。指定されたバイト数に至る前にファイルの終わりに達した場合、INVALID_OFFSETエラーが発生します。

  • absolute_offsetの場合、このプロシージャは、バイト数で指定された絶対位置を検索します。

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

GET_LINEプロシージャ

このプロシージャは、ファイル・ハンドルが示すオープン・ファイルからテキストを1行読み込んで、出力バッファ・パラメータに配置します。テキストは、ファイルまたはlenパラメータの最後まで読み込まれますが、行の終了記号は含まれません。FOPENに指定されているmax_linesizeを超えることはできません。

構文

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

パラメータ

表224-16 GET_LINEプロシージャのパラメータ

パラメータ 説明

file

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

ファイルは読込み用(モードr)としてオープンする必要があります。そうでない場合は、INVALID_OPERATION例外が発生します。

buffer

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

len

ファイルから読み込むバイト数。デフォルトはNULLです。NULLを指定すると、max_linesizeの値が設定されます。

例外

INVALID_FILEHANDLE

INVALID_OPERATION

NO_DATA_FOUND

READ_ERROR

使用上の注意

行がバッファに収まらない場合は、READ_ERROR例外が発生します。ファイルの終わりに到達したためにテキストが読み込まれなかった場合は、NO_DATA_FOUND例外が発生します。ファイルがバイト・モード操作用にオープンしている場合は、INVALID_OPERATION例外が発生します。

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

bufferパラメータの最大サイズは、より小さいサイズをFOPENに指定しないかぎり、32767バイトです。指定しない場合は、デフォルト値の1024が設定されます。「GET_LINE_NCHARプロシージャ」も参照してください。

GET_LINE_NCHARプロシージャ

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

ファイルは、各国語キャラクタ・セット・モードでオープンされ、UTF8キャラクタ・セットにエンコードされます。想定されるバッファのデータ・タイプは、NVARCHAR2です。別のデータ・タイプ(NCHAR、NCLOBまたはVARCHAR2など)の変数が指定されていると、テキストの読取り後にNVARCHAR2から標準の暗黙的な変換が実行されます。

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

構文

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

パラメータ

表224-17 GET_LINE_NCHARプロシージャのパラメータ

パラメータ 説明

file

FOPEN_NCHARコールが戻すアクティブなファイル・ハンドル。このファイルは読込み用(モードr)にオープンされる必要があります。ファイルをFOPEN_NCHARではなくFOPENでオープンした場合は、CHARSETMISMATCH例外が発生します。

buffer

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

len

ファイルから読み込むバイト数。デフォルトはNULLです。NULLを指定すると、max_linesizeの値が設定されます。

例外

INVALID_FILEHANDLE

INVALID_OPERATION

NO_DATA_FOUND

READ_ERROR

GET_RAWプロシージャ

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

構文

UTL_FILE.GET_RAW (
   file       IN            UTL_FILE.FILE_TYPE, 
   buffer     OUT NOCOPY    RAW, 
   len        IN            PLS_INTEGER DEFAULT NULL);

パラメータ

表224-18 GET_RAWプロシージャのパラメータ

パラメータ 説明

file

ファイル・ハンドル。

buffer

RAWデータ。

len

ファイルから読み込むバイト数。デフォルトはNULLです。NULLの場合、lenはRAWの最大長とみなされます。

例外

INVALID_FILEHANDLE

INVALID_OPERATION

LENGTH_MISMATCH

NO_DATA_FOUND

READ_ERROR

使用上の注意

このサブプログラムでは、ファイルの最後を超えて読込みを試みるときにNo_Data_Found例外が発生します。アプリケーションの処理ループ内でこの例外を捕捉して、この状態を許可する必要があります。

PROCEDURE Sys.p (n IN VARCHAR2) IS
      h     UTL_FILE.FILE_TYPE := UTL_FILE.FOPEN('D', n, 'r', 32767);
      Buf   RAW(32767);
      Amnt  CONSTANT PLS_INTEGER := 32767;
    BEGIN
      LOOP
        BEGIN
          Utl_File.Get_Raw(h, Buf, Amnt);
          -- Do something with this chunk
        EXCEPTION WHEN No_Data_Found THEN EXIT; END;
      END LOOP;
      UTL_FILE.FCLOSE (h);
    END;

IS_OPENファンクション

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

構文

UTL_FILE.IS_OPEN (
   file  IN FILE_TYPE)
  RETURN BOOLEAN;

パラメータ

表224-19 IS_OPENファンクションのパラメータ

パラメータ 説明

file

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

戻り値

TRUEまたはFALSE

例外

INVALID_FILEHANDLE

NEW_LINEプロシージャ

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

構文

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

パラメータ

表224-20 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 FILE_TYPE,
   buffer    IN VARCHAR2);

パラメータ

表224-21 PUTプロシージャのパラメータ

パラメータ 説明

file

FOPEN_NCHARコールが戻すアクティブなファイル・ハンドル。このファイルは書込み用にオープンされる必要があります。

buffer

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

ファイルはモードwまたはモードaを使用してオープンする必要があります。これ以外のモードを使用すると、INVALID_OPERATION例外が発生します。

使用上の注意

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

例外

INVALID_FILEHANDLE

INVALID_OPERATION

WRITE_ERROR

PUT_LINEプロシージャ

このプロシージャは、ファイル・ハンドルが示すオープン・ファイルに、バッファ・パラメータ内に格納されているテキスト文字列を書き込みます。このファイルは書込み操作用にオープンされる必要があります。PUT_LINEは、プラットフォーム固有の行終了文字または文字列で行を終了します。

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

構文

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

パラメータ

表224-22 PUT_LINEプロシージャのパラメータ

パラメータ 説明

file

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

buffer

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

autoflush

WRITEの後で、バッファをディスクにフラッシュします。

例外

INVALID_FILEHANDLE

INVALID_OPERATION

WRITE_ERROR

使用上の注意

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

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

PUT_LINE_NCHARプロシージャ

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

構文

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

パラメータ

表224-23 PUT_LINE_NCHARプロシージャのパラメータ

パラメータ 説明

file

FOPEN_NCHARコールが戻すアクティブなファイル・ハンドル。このファイルは書込み用にオープンされる必要があります。

buffer

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

例外

INVALID_FILEHANDLE

INVALID_OPERATION

WRITE_ERROR

使用上の注意

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

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

PUT_NCHARプロシージャ

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

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

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

構文

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

パラメータ

表224-24 PUT_NCHARプロシージャのパラメータ

パラメータ 説明

file

FOPEN_NCHARコールが戻すアクティブなファイル・ハンドル。ファイルをFOPEN_NCHARではなくFOPENでオープンした場合は、CHARSETMISMATCH例外が発生します。

buffer

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

ファイルはモードwまたはモードaを使用してオープンする必要があります。これ以外のモードを使用すると、INVALID_OPERATION例外が発生します。

例外

INVALID_FILEHANDLE

INVALID_OPERATION

WRITE_ERROR

使用上の注意

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

PUTFプロシージャ

このプロシージャは、書式付きのPUTプロシージャです。これは、制限付きのprintf()のように動作します。「PUTF_NCHARプロシージャ」も参照してください。

構文

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

パラメータ

表224-25 PUTFプロシージャのパラメータ

パラメータ 説明

file

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

format

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

arg1..arg5

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

引数文字列は、書式文字列内の%s書式指定文字に、順序正しく置き換えられます。

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

使用上の注意

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

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

    文字列 意味
    %s この文字列を引数リスト内の次の引数の文字列値に置き換えます。
    \n 適切なプラットフォーム固有の行終了記号に置き換えます。

例外

INVALID_FILEHANDLE

INVALID_OPERATION

WRITE_ERROR

例

次に、行を書き込む例を示します。

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

my_world  varchar2(4) := 'Zork';
...
PUTF(my_handle, 'Hello, world!\nI come from %s with %s.\n',
                my_world,
                'greetings for all earthlings');

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

PUTF_NCHARプロシージャ

このプロシージャは、PUT_NCHARプロシージャの書式設定されたバージョンです。PUTF_NCHARを使用すると、データベース・キャラクタ・セットではなくUnicodeでテキスト・ファイルの書込みを実行できます。このプロシージャは、書式要素\nおよび%sを含む書式文字列を受け入れ、書式文字列内の%sの連続インスタンスを最大で5つの引数に置き換えることができます。書式文字列および引数に想定されるデータ・タイプは、NVARCHAR2です。

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

構文

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

パラメータ

表224-26 PUTF_NCHARプロシージャのパラメータ

パラメータ 説明

file

FOPEN_NCHARコールが戻すアクティブなファイル・ハンドル。このファイルは読込み用(モードr)にオープンされる必要があります。ファイルをFOPEN_NCHARではなくFOPENでオープンした場合は、CHARSETMISMATCH例外が発生します。

format

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

arg1..arg5

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

引数文字列は、書式文字列内の%s書式指定文字に、順序正しく置き換えられます。

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

例外

INVALID_FILEHANDLE

INVALID_OPERATION

WRITE_ERROR

使用上の注意

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

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

PUT_RAWプロシージャ

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

構文

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

パラメータ

表224-27 PUT_RAWプロシージャのパラメータ

パラメータ 説明

file

ファイル・ハンドル。

buffer

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

autoflush

TRUEの場合は、出力バッファに値を書き込んだ後でフラッシュを実行します。デフォルトはFALSEです。

例外

INVALID_FILEHANDLE

INVALID_OPERATION

WRITE_ERROR

使用上の注意

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

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

  前
前 		 次
次
  目次へ移動
目次		 索引へ移動
索引