| Oracle Database PL/SQLパッケージ・プロシージャおよびタイプ・リファレンス 11g リリース1（11.1） E05686-02 |
|
 戻る |
 次へ |
UTL_FILEパッケージを使用して、PL/SQLプログラムでオペレーティング・システムのテキスト・ファイルの読込みと書込みができます。 UTL_FILEは、オペレーティング・システムのストリーム・ファイルI/Oの制約付きバージョンを提供します。
この章では、次の項目について説明します。
セキュリティ・モデル
タイプ
ルールおよび制限
例外
例
ユーザーがUTL_FILEを使用してアクセスできるファイルおよびディレクトリのセットは、ファクタおよびデータベース・パラメータの数によって制御されます。最初にアクセスできるのは、ユーザーが権限を付与されているディレクトリ・オブジェクトのセットです。
ユーザーがディレクトリ・オブジェクトuser_dirに対してREADとWRITEの両方のアクセス権を持つ場合、アクセス可能なディレクトリにあるファイルを開くことはできますが、サブディレクトリや親ディレクトリにあるファイルを開くことはできません。ファイルがリンクである場合、ユーザーはそのファイルを開くこともできる可能性があります。
最後に、クライアント側（テキスト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の外部でこれらのファイルを読む必要がある場合は、システム管理者からのアクセス権の入手が必要になることがあります。
|
注意:
|
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_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は行終了記号を無視し、GET_RAW lenパラメータによって要求された実際のバイト数を戻します。
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例外を使用して、ユーザーにエラーが戻されます。 |
表206-1 UTL_FILEパッケージの例外
| 例外名 | 説明 |
|---|---|
|
|
ファイルの場所が無効です。 |
|
|
|
|
|
ファイル・ハンドルが無効です。 |
|
|
要求どおりにファイルをオープンできないか、または操作できません。 |
|
|
読込み操作中にオペレーティング・システムのエラーが発生しました。 |
|
|
書込み操作中にオペレーティング・システムのエラーが発生しました。 |
|
|
PL/SQL内の未指定エラー。 |
|
|
ファイルは |
|
|
要求した操作は、ファイルがオープンしているため失敗しました。 |
|
|
|
|
|
ファイル名パラメータが無効です。 |
|
|
ファイルの場所に対するアクセス許可が拒否されました。 |
|
|
|
|
|
要求したファイルの削除操作に失敗しました。 |
|
|
要求したファイル名変更操作に失敗しました。 |
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;
表206-2 UTL_FILEサブプログラム
| サブプログラム | 説明 |
|---|---|
|
|
ファイルをクローズします。 |
|
|
オープンしているファイル・ハンドルをすべてクローズします。 |
|
|
ファイルの連続部分を新規に作成したファイルにコピーします。 |
|
|
保留中のすべての出力データを物理的にファイルへ書き込みます。 |
|
|
ディスク・ファイルの属性を読み込んで戻します。 |
|
|
ファイル内の現行の相対オフセット位置をバイト数で戻します。 |
|
|
入力用または出力用にファイルをオープンします。 |
|
|
入力用または出力用にファイルをUnicodeでオープンします。 |
|
|
ユーザーに十分な権限があるという前提で、ディスク・ファイルを削除します。 |
|
|
UNIXの |
|
|
指定したバイトの数だけ、ファイル内でポインタを前方または後方に調整します。 |
|
|
オープンしているファイルからテキストを読み込みます。 |
|
|
オープンしているファイルからテキストをUnicodeで読み込みます。 |
|
|
|
|
|
ファイル・ハンドルが、オープンしているファイルを参照しているかどうかを判別します。 |
|
|
1つ以上のOS固有の行終了記号をファイルに書き込みます。 |
|
|
ファイルに1つの文字列を書き込みます。 |
|
|
ファイルに1行書き込み、それによってOS固有の行終了記号を1つ追加します。 |
|
|
ファイルにUnicode行を1行書き込みます。 |
|
|
ファイルに1つのUnicode文字列を書き込みます。 |
|
|
書式付きの |
|
|
書式付きの |
|
|
|
このプロシージャは、ファイル・ハンドルが示すオープン・ファイルをクローズします。
構文
UTL_FILE.FCLOSE ( file IN OUT FILE_TYPE);
パラメータ
使用上の注意
FCLOSEの実行時に、まだ書き込んでいないデータがバッファに残っていると、ファイルのクローズ時にWRITE_ERROR例外を受け取る場合があります。
例外
WRITE_ERROR INVALID_FILEHANDLE
このプロシージャは、セッションでオープンしているすべてのファイル・ハンドルをクローズします。これは、PL/SQLプログラムの例外終了などの非常時のクリーンアップ・プロシージャとして使用します。
構文
UTL_FILE.FCLOSE_ALL;
使用上の注意
|
注意: FCLOSE_ALLは、ユーザーが保持しているオープン・ファイル・ハンドルの状態は変更しません。 つまり、FCLOSE_ALLコール後のファイル・ハンドルのIS_OPENテストでは、たとえファイルがすでにクローズしていてもTRUEが戻されます。 FCLOSE_ALLの前にオープンされたファイルには、以降の読込み操作や書込み操作を行うことができません。 |
例外
WRITE_ERROR
このプロシージャは、ファイルの連続部分を新規に作成したファイルにコピーします。 デフォルトでは、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);
パラメータ
表206-4 FCOPYプロシージャのパラメータ
| パラメータ | 説明 |
|---|---|
|
|
ソース・ファイルのディレクトリ位置。 |
|
|
コピー対象のソース・ファイル。 |
|
|
宛先ファイルが作成される宛先ディレクトリ。 |
|
|
ソース・ファイルから作成された宛先ファイル。 |
|
|
コピー操作を開始する行の番号。デフォルトは、最初の行の |
|
|
コピー操作を停止する行の番号。デフォルトは、ファイルの最後を示す |
FFLUSHは、ファイル・ハンドルが示すファイルに、保留中のデータを物理的に書き込みます。ファイルに書き込むデータは通常バッファリングされます。FFLUSHプロシージャは、バッファリングされているデータを強制的にファイルに書き込みます。データは改行文字で終了する必要があります。
フラッシュは、まだオープンしているファイルを読み込む必要がある場合に役立ちます。たとえば、デバッグ・メッセージをファイルにフラッシュして、即時に読み込むことができます。
構文
UTL_FILE.FFLUSH ( file IN FILE_TYPE); invalid_maxlinesize EXCEPTION;
パラメータ
例外
INVALID_FILEHANDLE INVALID_OPERATION WRITE_ERROR
このプロシージャは、ディスク・ファイルの属性を読み込んで戻します。
構文
UTL_FILE.FGETATTR( location IN VARCHAR2, filename IN VARCHAR2, fexists OUT BOOLEAN, file_length OUT NUMBER, blocksize OUT BINARY_INTEGER);
パラメータ
表206-6 FGETATTRプロシージャのパラメータ
| パラメータ | 説明 |
|---|---|
|
|
ソース・ファイルのディレクトリ位置。 |
|
|
検証されるファイルの名前。 |
|
|
ファイルが存在するかどうかを示す |
|
|
ファイルの長さ（バイト単位）。ファイルが存在しない場合は |
|
|
ファイル・システムのブロック・サイズ（バイト単位）。ファイルが存在しない場合は |
このファンクションは、ファイル内の現行の相対オフセット位置をバイト数で戻します。
構文
UTL_FILE.FGETPOS ( fileid IN file_type) RETURN PLS_INTEGER;
パラメータ
戻り値
FGETPOSは、オープン・ファイルの相対的なオフセット位置をバイト数で戻します。ファイルがオープンしていない場合は、例外が発生します。ファイルの先頭では、0（ゼロ）が戻されます。
使用上の注意
ファイルがバイト・モード操作用にオープンしている場合は、INVALID OPERATION例外が発生します。
このファンクションは、ファイルをオープンします。最大行サイズを指定でき、最大50ファイルまで同時にオープンできます。 「FOPEN_NCHARファンクション」も参照してください。
構文
UTL_FILE.FOPEN ( location IN VARCHAR2, filename IN VARCHAR2, open_mode IN VARCHAR2, max_linesize IN BINARY_INTEGER) RETURN file_type;
パラメータ
表206-8 FOPENファンクションのパラメータ
| パラメータ | 説明 |
|---|---|
|
|
ファイルのディレクトリ位置。この文字列はディレクトリのオブジェクト名で、大/小文字が区別されます。デフォルトは大文字です。 |
|
|
拡張子（ファイル・タイプ）も含めたファイル名。ディレクトリ・パスはありません。ディレクトリ・パスがファイル名の一部として指定される場合も、 |
|
|
ファイルのオープン方法を指定します。次のモードがあります。 r -- テキストの読込み w -- テキストの書込み a -- テキストの追加 rb -- バイトの読込み wb -- バイトの書込み ab -- バイトの追加
|
|
|
改行文字を含むこのファイルの1行当たりの最大文字数（最小値は1、最大値は32767）。指定がない場合、デフォルト値の1024が設定されます。 |
戻り値
FOPENは、そのファイルを操作する後続プロシージャすべてに渡す必要のあるファイル・ハンドルを戻します。 ファイル・ハンドルの特定の内容は、UTL_FILEパッケージ専用であり、UTL_FILEのユーザーは、個々のコンポーネントの参照または変更を行わないでください。
使用上の注意
ファイルの場所とファイル名の各パラメータは、引用符付きの文字列として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.
このファンクションは、指定した最大行サイズで入力用または出力用ファイルを各国語キャラクタ・セット・モードでオープンします。最大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) RETURN file_type;
パラメータ
表206-10 FOPEN_NCHARファンクションのパラメータ
| パラメータ | 説明 |
|---|---|
|
|
ファイルのディレクトリ位置。 |
|
|
ファイル名（拡張子を含む）。 |
|
|
ファイルをオープンするモード（r、w、a、rb、wb、ab）。 |
|
|
改行文字を含むこのファイルの1行当たりの最大文字数。（最小値は1、最大値は32767）。 |
このプロシージャは、ユーザーに十分な権限があるという前提で、ディスク・ファイルを削除します。
構文
UTL_FILE.FREMOVE ( location IN VARCHAR2, filename IN VARCHAR2);
パラメータ
表206-11 FREMOVEプロシージャのパラメータ
| パラメータ | 説明 |
|---|---|
|
|
ファイルのディレクトリ位置。 |
|
|
削除されるファイルの名前。 |
使用上の注意
FREMOVEプロシージャでは、ファイルを削除する前に権限の有無を検証しません。ファイルとディレクトリに対するアクセス権限は、O/Sによって検証されます。障害時には、例外が戻されます。
このプロシージャは、UNIXのmvファンクションと同じように、既存のファイルに新規の名前を指定します。
構文
UTL_FILE.FRENAME ( location IN VARCHAR2, filename IN VARCHAR2, dest_dir IN VARCHAR2, dest_file IN VARCHAR2, overwrite IN BOOLEAN DEFAULT FALSE);
パラメータ
表206-12 FRENAMEプロシージャのパラメータ
| パラメータ | 説明 |
|---|---|
|
|
ソース・ファイルのディレクトリ位置。 |
|
|
名前変更対象のソース・ファイル。 |
|
|
宛先ファイルの宛先ディレクトリ。 |
|
|
ファイルの新しい名前。 |
|
|
デフォルトは |
使用上の注意
ソース・ディレクトリと宛先ディレクトリの両方に対するアクセス権限の付与が必要です。宛先ディレクトリにファイルがある場合は、overwriteパラメータを使用して、そのファイルを上書きするかどうかを指定できます。デフォルトは、上書きしない場合のFALSEです。
このプロシージャは、指定したバイトの数だけ、ファイル内でポインタを前方または後方に調整します。
構文
UTL_FILE.FSEEK ( fid IN utl_file.file_type, absolute_offset IN PL_INTEGER DEFAULT NULL, relative_offset IN PLS_INTEGER DEFAULT NULL);
パラメータ
表206-13 FSEEKプロシージャのパラメータ
| パラメータ | 説明 |
|---|---|
|
|
ファイルID。 |
|
|
検索先の絶対位置。デフォルト= |
|
|
前方または後方に検索するバイト数。正数=前方、負の整数=後方、0（ゼロ）=現在の位置、デフォルト= |
使用上の注意
FSEEKを使用すると、最初にファイルのクローズと再オープンを行わずに、ファイル内の前の行を読み込むことができます。ナビゲートするバイト数を把握しておく必要があります。
relative_offsetを使用する場合、このプロシージャはrelative_offset > 0の場合に前方検索、relative_offset < 0の場合に後方検索を行い、指定されたrelative_offsetバイトの数だけファイルを検索します。
指定されたバイト数に至る前にファイルの先頭まで到達した場合、ファイル・ポインタはファイルの先頭に置かれます。 指定されたバイト数に至る前にファイルの終わりに達した場合、INVALID_OFFSETエラーが発生します。
absolute_offsetの場合、このプロシージャは、バイト数で指定された絶対位置を検索します。
ファイルがバイト・モード操作用にオープンしている場合は、INVALID OPERATION例外が発生します。
このプロシージャは、ファイル・ハンドルが示すオープン・ファイルからテキストを1行読み込んで、出力バッファ・パラメータに配置します。テキストは、ファイルまたはlenパラメータの最後まで読み込まれますが、行の終了記号は含まれません。 FOPENに指定されているmax_linesizeを超える読込みはできません。
構文
UTL_FILE.GET_LINE ( file IN FILE_TYPE, buffer OUT VARCHAR2, len IN PLS_INTEGER DEFAULT NULL);
パラメータ
表206-14 GET_LINEプロシージャのパラメータ
| パラメータ | 説明 |
|---|---|
|
|
ファイルは読込み用（モード |
|
|
ファイルから読み込まれた行を受け取るデータ・バッファ。 |
|
|
ファイルから読み込むバイト数。デフォルトは |
使用上の注意
行がバッファに収まらない場合は、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
このプロシージャは、ファイル・ハンドルが示すオープン・ファイルからテキストを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);
パラメータ
表206-15 GET_LINE_NCHARプロシージャのパラメータ
| パラメータ | 説明 |
|---|---|
|
|
|
|
|
ファイルから読み込まれた行を受け取るデータ・バッファ。 |
|
|
ファイルから読み込むバイト数。デフォルトは |
このファンクションは、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);
パラメータ
表206-16 GET_RAWファンクションのパラメータ
| パラメータ | 説明 |
|---|---|
|
|
ファイルID。 |
|
|
|
|
|
ファイルから読み込むバイト数。デフォルトは |
使用上の注意
このサブプログラムでは、ファイルの最後を超えて読込みを試みるときに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は、ファイル・ハンドルが、オープン状態でクローズしていないファイルを示しているかどうかを通知するのみです。このファンクションは、ユーザーがファイル・ハンドルを使用しようとしたときに、オペレーティング・システムのエラーが発生しないことを保証するものではありません。
構文
UTL_FILE.IS_OPEN ( file IN FILE_TYPE) RETURN BOOLEAN;
パラメータ
戻り値
TRUEまたはFALSE
このプロシージャは、入力ファイル・ハンドルが示すファイルに、1つ以上の行終了記号を書き込みます。行終了記号はプラットフォーム固有の文字や文字列であるため、このプロシージャはPUTとは異なります。
構文
UTL_FILE.NEW_LINE ( file IN FILE_TYPE, lines IN NATURAL := 1);
パラメータ
表206-18 NEW_LINEプロシージャのパラメータ
| パラメータ | 説明 |
|---|---|
|
|
|
|
|
ファイルに書き込む行終了記号の数。 |
例外
INVALID_FILEHANDLE INVALID_OPERATION WRITE_ERROR
PUTプロシージャは、ファイル・ハンドルが示すオープン・ファイルに、バッファ・パラメータ内に格納されているテキスト文字列を書き込みます。このファイルは書込み操作用にオープンされる必要があります。 PUTは、行終了記号を追加しません。行の終了にはNEW_LINEを使用するか、またはPUT_LINEを使用して行終了記号付きの完全な1行を書き込んでください。 「PUT_NCHARプロシージャ」も参照してください。
構文
UTL_FILE.PUT ( file IN FILE_TYPE, buffer IN VARCHAR2);
パラメータ
表206-19 PUTプロシージャのパラメータ
| パラメータ | 説明 |
|---|---|
|
|
|
|
|
ファイルに書き込むテキストを含んだバッファ。 ファイルはモード |
使用上の注意
bufferパラメータの最大サイズは、より小さいサイズをFOPENに指定しないかぎり、32767バイトです。指定しない場合は、デフォルト値の1024が選択されます。連続したPUTコールの全合計は、途中でバッファ・フラッシュをしないかぎり、32767を超えません。
例外
INVALID_FILEHANDLE INVALID_OPERATION WRITE_ERROR
このプロシージャは、ファイル・ハンドルが示すオープン・ファイルに、バッファ・パラメータ内に格納されているテキスト文字列を書き込みます。このファイルは書込み操作用にオープンされる必要があります。 PUT_LINEは、プラットフォーム固有の行終了文字または文字列で行を終了します。
「PUT_LINE_NCHARプロシージャ」も参照してください。
構文
UTL_FILE.PUT_LINE ( file IN FILE_TYPE, buffer IN VARCHAR2, autoflush IN BOOLEAN DEFAULT FALSE);
パラメータ
表206-20 PUT_LINEプロシージャのパラメータ
| パラメータ | 説明 |
|---|---|
|
|
|
|
|
ファイルに書き込む行を含んだテキスト・バッファ。 |
|
|
|
使用上の注意
bufferパラメータの最大サイズは、より小さいサイズをFOPENに指定しないかぎり、32767バイトです。指定しない場合は、デフォルト値の1024が選択されます。連続したPUTコールの全合計は、途中でバッファ・フラッシュをしないかぎり、32767を超えません。
ファイルがバイト・モード操作用にオープンしている場合は、INVALID OPERATION例外が発生します。
例外
INVALID_FILEHANDLE INVALID_OPERATION WRITE_ERROR
このプロシージャは、ファイル・ハンドルが示すオープン・ファイルに、バッファ・パラメータ内に格納されているテキスト文字列を書き込みます。このファンクションを使用すると、データベース・キャラクタ・セットではなくUnicodeでテキスト・ファイルの書込みを実行できます。 このプロシージャは、書き込まれたテキストに行セパレータが追加されることを除いて、PUT_NCHARプロシージャと同じです。 「PUT_LINEプロシージャ」も参照してください。
構文
UTL_FILE.PUT_LINE_NCHAR ( file IN FILE_TYPE, buffer IN NVARCHAR2);
パラメータ
表206-21 PUT_LINE_NCHARプロシージャのパラメータ
| パラメータ | 説明 |
|---|---|
|
|
|
|
|
ファイルに書き込む行を含んだテキスト・バッファ。 |
使用上の注意
bufferパラメータの最大サイズは、より小さいサイズをFOPENに指定しないかぎり、32767バイトです。指定しない場合は、デフォルト値の1024が選択されます。連続したPUTコールの全合計は、途中でバッファ・フラッシュをしないかぎり、32767を超えません。
ファイルがバイト・モード操作用にオープンしている場合は、INVALID OPERATION例外が発生します。
このプロシージャは、ファイル・ハンドルが示すオープン・ファイルに、バッファ・パラメータ内に格納されているテキスト文字列を書き込みます。
このファンクションを使用すると、データベース・キャラクタ・セットではなくUnicodeでテキスト・ファイルの書込みを実行できます。このファイルは、各国語キャラクタ・セット・モードでオープンされる必要があります。 テキスト文字列は、UTF8キャラクタ・セットで書き込まれます。 想定されるバッファのデータ型は、NVARCHAR2です。 別のデータ型の変数が指定されていると、テキストの書込み前にNVARCHAR2への暗黙的な変換が実行されます。
「PUTプロシージャ」も参照してください。
構文
UTL_FILE.PUT_NCHAR ( file IN FILE_TYPE, buffer IN NVARCHAR2);
パラメータ
表206-22 PUT_NCHARプロシージャのパラメータ
| パラメータ | 説明 |
|---|---|
|
|
|
|
|
ファイルに書き込むテキストを含んだバッファ。 ファイルはモード |
使用上の注意
bufferパラメータの最大サイズは、より小さいサイズをFOPENに指定しないかぎり、32767バイトです。指定しない場合は、デフォルト値の1024が選択されます。連続したPUTコールの全合計は、途中でバッファ・フラッシュをしないかぎり、32767を超えません。
このプロシージャは、書式付きのPUTプロシージャです。これは、制限付きのprintf()のように動作します。 「PUTF_NCHARプロシージャ」も参照してください。
構文
UTL_FILE.PUTF ( file IN FILE_TYPE, format IN VARCHAR2, [arg1 IN VARCHAR2 DEFAULT NULL, . . . arg5 IN VARCHAR2 DEFAULT NULL]);
パラメータ
表206-23 PUTFプロシージャのパラメータ
| パラメータ | 説明 |
|---|---|
|
|
|
|
|
テキストや書式文字 |
|
|
1から5個までのオプションの引数文字列。 引数文字列は、書式文字列内の 引数より多い書式指定文字が書式パラメータ文字列内にある場合は、引数のない各 |
使用上の注意
ファイルがバイト・モード操作用にオープンしている場合は、INVALID OPERATION例外が発生します。
書式文字列には任意のテキストを指定できますが、文字列%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
このプロシージャは、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]);
パラメータ
表206-24 PUTF_NCHARプロシージャのパラメータ
| パラメータ | 説明 |
|---|---|
|
|
|
|
|
テキストや書式文字 |
|
|
1から5個までのオプションの引数文字列。 引数文字列は、書式文字列内の%s書式指定文字に、順序正しく置き換えられます。 引数より多い書式指定文字が書式パラメータ文字列内にある場合は、引数のない各%sは空の文字列に置き換えられます。 |
使用上の注意
bufferパラメータの最大サイズは、より小さいサイズをFOPENに指定しないかぎり、32767バイトです。指定しない場合は、デフォルト値の1024が選択されます。連続したPUTコールの全合計は、途中でバッファ・フラッシュをしないかぎり、32767を超えません。
ファイルがバイト・モード操作用にオープンしている場合は、INVALID OPERATION例外が発生します。
このプロシージャは、RAWデータ値を入力として受け入れ、出力バッファに書き込みます。
構文
UTL_FILE.PUT_RAW ( fid IN utl_file.file_type, r IN RAW, autoflush IN BOOLEAN DEFAULT FALSE);
パラメータ
表206-25 PUT_RAWファンクションのパラメータ
| パラメータ | 説明 |
|---|---|
|
|
ファイルID。 |
|
|
バッファに書き込まれた |
|
|
|
使用上の注意
3番目の引数をTRUEに設定することで、バッファの自動フラッシュを要求できます。
bufferパラメータの最大サイズは、より小さいサイズをFOPENに指定しないかぎり、32767バイトです。指定しない場合は、デフォルト値の1024が選択されます。連続したPUTコールの全合計は、途中でバッファ・フラッシュをしないかぎり、32767を超えません。
