ヘッダーをスキップ
Oracle Database PL/SQLパッケージ・プロシージャおよびタイプ・リファレンス
10g リリース2(10.2)
B19245-02
  目次
目次
索引
索引

戻る
戻る
 
次へ
次へ
 

168 UTL_FILE

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

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


UTL_FILEの使用方法


セキュリティ・モデル

UTL_FILEは、PL/SQLのクライアント側とサーバー側の両方で使用可能です。クライアント側(テキストI/O)とサーバー側の両方の実装について、サーバー側のファイル・システムに対するアクセス権限のチェックが行われます。

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


注意:

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

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


注意:

  •  

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

  • 無効なオプションを適用しようとすると、予期できない結果が生じます。



データ型

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

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

使用上の注意

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

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

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

UTL_FILE.GET_RAWは行終了記号を無視し、GET_RAW lenパラメータによって要求された実際のバイト数を戻します。

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


ルールおよび制限

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

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


注意:

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


例外

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

例外名 説明

INVALID_PATH

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

INVALID_MODE

FOPENopen_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_FOUNDVALUE_ERRORなどの事前定義済のPL/SQL例外を発生させることもあります。


例1


注意:

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

次の文があるとします。

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

SQL> CREATE DIRECTORY out_dir AS '/appl/gl/user'';
SQL> GRANT READ 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('MYDIR','MYFILE','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('MYDIR','MYFILE','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('MYDIR','MYFILE','R');
  UTL_FILE.GET_LINE(F1,V1);
  UTL_FILE.FCLOSE(F1);
END;

UTL_FILEサブプログラムの要約

表168-2 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);

パラメータ

表168-3 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 (
   location   IN VARCHAR2,
   filename   IN VARCHAR2,
   dest_dir   IN VARCHAR2,
   dest_file  IN VARCHAR2,
   start_line IN PLS_INTEGER DEFAULT 1,
   end_line   IN PLS_INTEGER DEFAULT NULL);

パラメータ

表168-4 FCOPYプロシージャのパラメータ

パラメータ 説明

location

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

filename

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

dest_dir

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

dest_file

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

start_line

コピー操作を開始する行の番号。デフォルトは、最初の行の1です。

end_line

コピー操作を停止する行の番号。デフォルトは、ファイルの最後を示すNULLです。



FFLUSHプロシージャ

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

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

構文

UTL_FILE.FFLUSH (
   file  IN FILE_TYPE);
invalid_maxlinesize  EXCEPTION;

パラメータ

表168-5 FFLUSHプロシージャのパラメータ

パラメータ 説明

file

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


例外

INVALID_FILEHANDLE
INVALID_OPERATION
WRITE_ERROR

FGETATTRプロシージャ

このプロシージャは、ディスク・ファイルの属性を読み込んで戻します。

構文

UTL_FILE.FGETATTR(
   location    IN VARCHAR2,
   filename    IN VARCHAR2,
   exists      OUT BOOLEAN,
   file_length OUT NUMBER,
   blocksize   OUT NUMBER);

パラメータ

表168-6 FGETATTRプロシージャのパラメータ

パラメータ 説明

location

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

filename

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

exists

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

file_length

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

blocksize

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



FGETPOSファンクション

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

構文

UTL_FILE.FGETPOS (
   fileid IN file_type)
 RETURN PLS_INTEGER;

パラメータ

表168-7 FGETPOSのパラメータ

パラメータ 説明

fileid

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


戻り値

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


FOPENファンクション

このファンクションは、ファイルをオープンします。最大行サイズを指定でき、最大50ファイルまで同時にオープンできます。「FOPEN_NCHARファンクション」も参照してください。

構文

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

パラメータ

表168-8 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のユーザーは、個々のコンポーネントの参照または変更を行わないでください。

表168-9 FOPENファンクションの戻り値

戻り値 説明

file_type

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


使用上の注意

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

例外

INVALID_PATH: File location or name was invalid.
INVALID_MODE: The open_mode string was invalid.
INVALID_OPERATION: File could not be opened as requested.
INVALID_MAXLINESIZE: Specified max_linesize is too large or too small.

FOPEN_NCHARファンクション

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

構文

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

パラメータ

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

パラメータ 説明

location

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

filename

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

open_mode

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

max_linesize

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



FREMOVEプロシージャ

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

構文

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

パラメータ

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

パラメータ 説明

location

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

filename

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


使用上の注意

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


FRENAMEプロシージャ

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

構文

UTL_FILE.FRENAME (
   location  IN VARCHAR2,
   filename  IN VARCHAR2,
   dest_dir  IN VARCHAR2,
   dest_file IN VARCHAR2,
   overwrite IN BOOLEAN DEFAULT FALSE);

パラメータ

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

パラメータ 説明

location

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

filename

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

dest_dir

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

dest_file

ファイルの新しい名前。

overwrite

デフォルトはFALSEです。


使用上の注意

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


FSEEKプロシージャ

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

構文

UTL_FILE.FSEEK (
   fid             IN utl_file.file_type,
   absolute_offset IN PL_INTEGER DEFAULT NULL,
   relative_offset IN PLS_INTEGER DEFAULT NULL);

パラメータ

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

パラメータ 説明

fid

ファイルID。

absolute_offset

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

relative_offset

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


使用上の注意

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

relative_offsetでは、relative_offset > 0の場合は前方に、relative_offset < 0の場合は後方に、relative_offsetに指定されたバイト数だけ検索されます。

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

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


GET_LINEプロシージャ

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

構文

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

パラメータ

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

パラメータ 説明

file

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

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

buffer

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

len

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


使用上の注意

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

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

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

例外

INVALID_FILEHANDLE
INVALID_OPERATION
READ_ERROR
NO_DATA_FOUND
VALUE_ERROR

GET_LINE_NCHARプロシージャ

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

構文

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

パラメータ

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

パラメータ 説明

file

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

buffer

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

len

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



GET_RAWファンクション

このファンクションは、RAW文字列値をファイルから読み込み、読み込んだバイトの数だけ、ファイルのポインタを前方に調整します。UTL_FILE.GET_RAWは行終了記号を無視し、GET_RAW lenパラメータによって要求された実際のバイト数を戻します。

構文

UTL_FILE.GET_RAW (
   fid  IN  utl_file.file_type,
   r    OUT NOCOPY RAW,
   len  IN  PLS_INTEGER DEFAULT NULL);

パラメータ

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

パラメータ 説明

fid

ファイルID。

r

RAWデータ。

len

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



IS_OPENファンクション

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

構文

UTL_FILE.IS_OPEN (
   file  IN FILE_TYPE)
  RETURN BOOLEAN;

パラメータ

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

パラメータ 説明

file

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


戻り値

TRUEまたはFALSE


NEW_LINEプロシージャ

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

構文

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

パラメータ

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

パラメータ

表168-19 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);

パラメータ

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

パラメータ 説明

file

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

buffer

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

autoflush

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


使用上の注意

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

例外

INVALID_FILEHANDLE
INVALID_OPERATION
WRITE_ERROR

PUT_LINE_NCHARプロシージャ

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

構文

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

パラメータ

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

パラメータ 説明

file

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

buffer

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


使用上の注意

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


PUT_NCHARプロシージャ

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

構文

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

パラメータ

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

パラメータ 説明

file

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

buffer

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

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


使用上の注意

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

パラメータ

表168-23 PUTFプロシージャのパラメータ

パラメータ 説明

file

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

format

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

arg1..arg5

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

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

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


使用上の注意

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

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

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

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は空の文字列に置き換えられます。

例外

INVALID_FILEHANDLE
INVALID_OPERATION
WRITE_ERROR

PUTF_NCHARプロシージャ

このプロシージャは、書式化されたPUT_NCHARプロシージャです。PUTF_NCHARを使用すると、データベース・キャラクタ・セットではなくUnicodeでテキスト・ファイルの書込みを実行できます。

構文

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

パラメータ

表168-24 PUTF_NCHARプロシージャのパラメータ

パラメータ 説明

file

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

format

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

arg1..arg5

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

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

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


使用上の注意

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


PUT_RAWプロシージャ

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

構文

UTL_FILE.PUT_RAW (
   fid       IN utl_file.file_type,
   r         IN RAW,
   autoflush IN BOOLEAN DEFAULT FALSE);

パラメータ

表168-25 PUT_RAWプロシージャのパラメータ

パラメータ 説明

fid

ファイルID。

r

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

autoflush

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


使用上の注意

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

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