276 UTL_FILE
UTL_FILEパッケージを使用して、PL/SQLプログラムでオペレーティング・システムのテキスト・ファイルの読込みと書込みができます。UTL_FILEは、オペレーティング・システムのストリーム・ファイルI/Oの制約付きバージョンを提供します。
この章のトピックは、次のとおりです:
276.1 UTL_FILEのセキュリティ・モデル
ユーザーがUTL_FILEを使用してアクセスできるファイルおよびディレクトリのセットは、ファクタおよびデータベース・パラメータの数によって制御されます。最初にアクセスできるのは、ユーザーが権限を付与されているディレクトリ・オブジェクトのセットです。
ディレクトリ・オブジェクトの性質については、『Oracle Database SQL言語リファレンス』を参照してください。
ユーザーがディレクトリ・オブジェクトUSER_DIRに対してREADとWRITEの両方のアクセス権を持つ場合、USER_DIRで記述されているオペレーティング・システム・ディレクトリにあるファイルを開くことはできますが、このディレクトリのサブディレクトリや親ディレクトリにあるファイルを開くことはできません。
最後に、クライアント側(テキストI/O)とサーバー側の両方の実装について、オペレーティング・システム・ファイルに対するアクセス権限のチェックが行われます。
UTL_FILEでは、クライアント側とサーバー側の両方からのファイル・アクセスが提供されています。UTL_FILEをサーバー上で実行すると、そのサーバーからアクセスできるすべてのオペレーティング・システム・ファイルにアクセスできます。クライアント側では、Formsアプリケーションの場合と同様に、UTL_FILEによって、クライアントからアクセスできるオペレーティング・システム・ファイルへのアクセスが提供されます。
UTL_FILEのアプリケーション管理者による柔軟できめ細かい制御を可能にするディレクトリ・オブジェクトは、動的に(データベースを停止しないで)メンテナンスでき、Oracleの他のツールとの一貫性を保持しています。CREATE ANY DIRECTORY権限は、SYSおよびSYSTEMに対してのみデフォルトで付与されます。
ノート:
ディレクトリのアクセス検証には、CREATE DIRECTORY機能を使用します。
ハード・リンクまたはシンボリック・リンクのいずれもサポートされていないことに注意してください。
UNIXシステムでは、FOPENファンクションで作成したファイルにはそのファイルの所有者、つまりインスタンスを実行するシャドウ・プロセスの所有者がいます。通常、この所有者はORACLEです。FOPENを使用して作成されたファイルは、UTL_FILEサブプログラムを使用する書込みと読込みが常に可能です。ただし、権限のないオペレーティング・システムのユーザーがPL/SQLの外部でこれらのファイルを読む必要がある場合は、システム管理者からのアクセス権の入手が必要になることがあります。
警告:
ディレクトリ・オブジェクト内のファイルにアクセスするために必要な権限は、オペレーティング・システムに固有の権限です。UTL_FILEディレクトリ・オブジェクト権限によって、ユーザーには、特定ディレクトリ内のすべてのファイルに対する読取りと書込みのアクセス権限が与えられます。
276.2 UTL_FILEの操作上のノート
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を設定する場合は、データベースの文字セットと同じものにする必要があります。
276.3 UTL_FILEのルールおよび制限
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例外を使用して、ユーザーにエラーが戻されます。
276.4 UTL_FILEの例外
この表は、UTL_FILEサブプログラムで発生する例外について説明しています。
表276-1 UTL_FILEパッケージの例外
| 例外名 | 説明 |
|---|---|
|
|
ファイルの場所が無効です。 |
|
|
|
|
|
ファイル・ハンドルが無効です。 |
|
|
要求どおりにファイルをオープンできないか、または操作できません。 |
|
|
宛先のバッファが小さすぎるか、または読取り操作中にオペレーティング・システムのエラーが発生しました。 |
|
|
書込み操作中にオペレーティング・システムのエラーが発生しました。 |
|
|
PL/SQL内の未指定エラー。 |
|
|
ファイルは |
|
|
要求した操作は、ファイルがオープンしているため失敗しました。 |
|
|
|
|
|
ファイル名パラメータが無効です。 |
|
|
ファイルの場所に対するアクセス許可が拒否されました。 |
|
|
|
|
|
要求したファイルの削除操作に失敗しました。 |
|
|
要求したファイル名変更操作に失敗しました。 |
UTL_FILEにおけるプロシージャでは、NO_DATA_FOUNDまたはVALUE_ERRORのような事前定義済のPL/SQL例外が発生することもあります。
276.5 UTL_FILEの例
次の2つの例は、プロシージャの使用方法を示しています。
例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;
有効でアクセス可能なファイルの場所とファイル名は、次のとおりです。
| ファイルの場所 | ファイル名 | 読込みおよび書込み |
|---|---|---|
|
|
|
DBA権限を持つユーザー |
|
|
|
すべてのユーザー |
次のファイルの場所とファイル名は無効です。
| ファイルの場所 | ファイル名 | 無効の理由 |
|---|---|---|
|
|
|
#サブディレクトリにアクセスできません。 |
|
|
|
#ディレクトリの文字列は、O/Sで要求されている大/小文字区別ルールに従う必要があります。 |
|
|
|
#ファイル名にディレクトリ・パスの一部が含まれていない可能性があります。 |
|
|
|
#対応する |
例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; 276.6 UTL_FILEのデータ構造
UTL_FILEパッケージは、レコード・タイプを定義します。
レコード・タイプ
276.6.1 FILETYPEレコード・タイプ
FILE_TYPEの内容は、UTL_FILEパッケージ専用です。このレコードのコンポーネントを参照または変更しないでください。
TYPE file_type IS RECORD ( id BINARY_INTEGER, datatype BINARY_INTEGER, byte_mode BOOLEAN);
フィールド
表276-2 FILE_TYPEのフィールド
| フィールド | 説明 |
|---|---|
|
|
内部ファイル・ハンドル番号を示す数値。 |
|
|
ファイルのタイプを示します( |
|
|
ファイルがバイナリ・ファイルとしてオープンされたか、テキスト・ファイルとしてオープンされたかを示します。 |
注意:
データベース・セッション間または単一セッション内でのFILE_TYPE値の永続性は保証されていません。ファイル・ハンドルのクローン化やダミー・ファイルの使用を試みると、予測できない結果が生じる可能性があります。
276.7 UTL_FILEサブプログラムの要約
この表は、UTL_FILEサブプログラムを示し、簡単に説明しています。
表276-3 UTL_FILEのサブプログラム
| サブプログラム | 説明 |
|---|---|
|
ファイルをクローズします。 |
|
|
オープンしているファイル・ハンドルをすべてクローズします。 |
|
|
ファイルの連続部分を新規に作成したファイルにコピーします。 |
|
|
保留中のすべての出力データを物理的にファイルへ書き込みます。 |
|
|
ディスク・ファイルの属性を読み込んで戻します。 |
|
|
ファイル内の現行の相対オフセット位置をバイト数で戻します。 |
|
|
入力用または出力用にファイルをオープンします。 |
|
|
入力用または出力用にファイルをUnicodeでオープンします。 |
|
|
ユーザーに十分な権限があるという前提で、ディスク・ファイルを削除します。 |
|
|
UNIXの |
|
|
指定したバイトの数だけ、ファイル内でポインタを前方または後方に調整します。 |
|
|
オープンしているファイルからテキストを読み込みます。 |
|
|
オープンしているファイルからテキストをUnicodeで読み込みます。 |
|
|
|
|
|
ファイル・ハンドルが、オープンしているファイルを参照しているかどうかを判別します。 |
|
|
1つ以上のオペレーティング・システム固有の行終了記号をファイルに書き込みます。 |
|
|
ファイルに1つの文字列を書き込みます。 |
|
|
ファイルに1行書き込み、それによってオペレーティング・システム固有の行終了記号を1つ追加します。 |
|
|
ファイルにUnicode行を1行書き込みます。 |
|
|
ファイルに1つのUnicode文字列を書き込みます。 |
|
|
書式付きの |
|
|
書式付きの |
|
|
|
276.7.1 FCLOSEプロシージャ
このプロシージャは、ファイル・ハンドルが示すオープン・ファイルをクローズします。
構文
UTL_FILE.FCLOSE ( file IN OUT FILE_TYPE);
パラメータ
表276-4 FCLOSEプロシージャのパラメータ
| パラメータ | 説明 |
|---|---|
|
|
|
使用上のノート
FCLOSEの実行時に、まだ書き込んでいないデータがバッファに残っていると、ファイルのクローズ時にWRITE_ERROR例外を受け取る場合があります。
例外
WRITE_ERROR INVALID_FILEHANDLE
276.7.2 FCLOSE_ALLプロシージャ
このプロシージャは、セッションでオープンしているすべてのファイル・ハンドルをクローズします。これは、たとえば、PL/SQLプログラムの例外終了時に、非常時のクリーンアップ・プロシージャとして使用されます。
構文
UTL_FILE.FCLOSE_ALL;
使用上のノート
ノート:
FCLOSE_ALLは、ユーザーが保持しているオープン・ファイル・ハンドルの状態は変更しません。つまり、FCLOSE_ALLコール後のファイル・ハンドルのIS_OPENテストでは、たとえファイルがすでにクローズしていてもTRUEが戻されます。FCLOSE_ALLの前にオープンされたファイルには、以降の読込み操作や書込み操作を行うことができません。
例外
WRITE_ERROR
276.7.3 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);
パラメータ
表276-5 FCOPYプロシージャのパラメータ
| パラメータ | 説明 |
|---|---|
|
|
ソース・ファイルのディレクトリ位置。 |
|
|
コピー対象のソース・ファイル。 |
|
|
宛先ファイルが作成される宛先ディレクトリ。 |
|
|
ソース・ファイルから作成された宛先ファイル。 |
|
|
コピー操作を開始する行の番号。デフォルトは、最初の行の |
|
|
コピー操作を停止する行の番号。デフォルトは、ファイルの最後を示す |
例外
INVALID_FILENAME
INVALID_PATH
INVALID_OPERATION
INVALID_OFFSET
READ_ERROR
WRITE_ERROR
276.7.4 FFLUSHプロシージャ
FFLUSHは、ファイル・ハンドルが示すファイルに、保留中のデータを物理的に書き込みます。ファイルに書き込むデータは通常バッファリングされます。FFLUSHプロシージャは、バッファリングされているデータを強制的にファイルに書き込みます。データは改行文字で終了する必要があります。
フラッシュは、まだオープンしているファイルを読み込む必要がある場合に役立ちます。たとえば、デバッグ・メッセージをファイルにフラッシュして、即時に読み込むことができます。
構文
UTL_FILE.FFLUSH ( file IN FILE_TYPE);
パラメータ
表276-6 FFLUSHプロシージャのパラメータ
| パラメータ | 説明 |
|---|---|
|
|
|
例外
INVALID_FILENAME
INVALID_MAXLINESIZE
INVALID_OPERATION
WRITE_ERROR
276.7.5 FGETATTRプロシージャ
このプロシージャは、ディスク・ファイルの属性を読み込んで戻します。
構文
UTL_FILE.FGETATTR( location IN VARCHAR2, filename IN VARCHAR2, fexists OUT BOOLEAN, file_length OUT NUMBER, block_size OUT BINARY_INTEGER);
パラメータ
表276-7 FGETATTRプロシージャのパラメータ
| パラメータ | 説明 |
|---|---|
|
|
ソース・ファイルのディレクトリ位置。 |
|
|
検証されるファイルの名前。 |
|
|
ファイルが存在するかどうかを示す |
|
|
ファイルの長さ(バイト単位)。ファイルが存在しない場合は |
|
|
ファイル・システムのブロック・サイズ(バイト単位)。ファイルが存在しない場合は |
例外
INVALID_PATH
INVALID_FILENAME
INVALID_OPERATION
READ_ERROR
ACCESS_DENIED
276.7.6 FGETPOSファンクション
このファンクションは、ファイル内の現行の相対オフセット位置をバイト数で戻します。
構文
UTL_FILE.FGETPOS ( file IN FILE_TYPE) RETURN PLS_INTEGER;
パラメータ
表276-8 FGETPOSのパラメータ
| パラメータ | 説明 |
|---|---|
|
|
ソース・ファイルのディレクトリ位置。 |
戻り値
FGETPOSは、オープン・ファイルの相対的なオフセット位置をバイト数で戻します。ファイルがオープンしていない場合は、例外が発生します。ファイルの先頭では、0が戻されます。
例外
INVALID_FILEHANDLE
INVALID_OPERATION
READ_ERROR
使用上のノート
ファイルがバイト・モード操作用にオープンしている場合は、INVALID OPERATION例外が発生します。
276.7.7 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;
パラメータ
表276-9 FOPENファンクションのパラメータ
| パラメータ | 説明 |
|---|---|
|
|
ファイルのディレクトリ位置。この文字列はディレクトリのオブジェクト名で、大文字で指定する必要があります。 |
|
|
拡張子(ファイル・タイプ)も含めたファイル名で、ディレクトリ・パスはありません。ディレクトリ・パスがファイル名の一部として指定される場合も、 |
|
|
ファイルのオープン方法を指定します。次のモードがあります。
|
|
|
改行文字を含むこのファイルの1行当たりの最大バイト数(最小値は1、最大値は32767)。指定がない場合は、デフォルト値である1024が指定されます。 |
戻り値
FOPENは、そのファイルを操作する後続プロシージャすべてに渡す必要のあるファイル・ハンドルを戻します。ファイル・ハンドルの特定の内容は、UTL_FILEパッケージ専用であり、UTL_FILEのユーザーは、個々のコンポーネントの参照または変更を行わないでください。
表276-10 FOPENファンクションの戻り値
| 戻り値 | 説明 |
|---|---|
|
|
オープン・ファイルのハンドル。 |
例外
INVALID_MAXILINESIZE
INVALID_MODE
INVALID_OPERATION
INVALID_PATH
INVALID_FILENAME
使用上のノート
ファイルの場所とファイル名の各パラメータは、引用符付きの文字列としてFOPENファンクションに指定する必要があります。これによってファイルの場所を、アクセス可能なディレクトリ・オブジェクトのALL_DIRECTORIESビューで指定されたアクセス可能なディレクトリのリストと照合してチェックできます。
276.7.8 FOPEN_NCHARファンクション
この関数は、最大行サイズを指定して、入力用または出力用のファイルを各国語文字セット・モードでオープンします。このファンクションを使用すると、データベース文字セットではなくUnicodeでテキスト・ファイルの読込みまたは書込みを実行できます。
最大50ファイルまで同時にオープンできます。
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;
パラメータ
表276-11 FOPEN_NCHARファンクションのパラメータ
| パラメータ | 説明 |
|---|---|
|
|
ファイルのディレクトリ位置。 |
|
|
ファイル名(拡張子を含む)。 |
|
|
ファイルをオープンするモード( |
|
|
改行文字を含むこのファイルの1行当たりの最大文字数(最小値は1、最大値は32767)。 |
戻り値
FOPEN_NCHARは、そのファイルを操作する後続プロシージャすべてに渡す必要のあるファイル・ハンドルを戻します。ファイル・ハンドルの特定の内容は、UTL_FILEパッケージ専用であり、UTL_FILEのユーザーは、個々のコンポーネントの参照または変更を行わないでください。
表276-12 FOPEN_NCHARファンクションの戻り値
| 戻り値 | 説明 |
|---|---|
|
|
オープン・ファイルのハンドル。 |
例外
INVALID_MAXILINESIZE
INVALID_MODE
INVALID_OPERATION
INVALID_PATH
276.7.9 FREMOVEプロシージャ
このプロシージャは、ユーザーに十分な権限があるという前提で、ディスク・ファイルを削除します。
構文
UTL_FILE.FREMOVE ( location IN VARCHAR2, filename IN VARCHAR2);
パラメータ
表276-13 FREMOVEプロシージャのパラメータ
| パラメータ | 説明 |
|---|---|
|
|
ファイルのディレクトリ位置。 |
|
|
削除されるファイルの名前。 |
例外
ACCESS_DENIED
DELETE_FAILED
INVALID_FILENAME
INVALID_OPERATION
INVALID_PATH
使用上のノート
FREMOVEプロシージャでは、ファイルを削除する前に権限の有無を検証しません。ファイルとディレクトリに対するアクセス権限は、O/Sによって検証されます。障害時には、例外が戻されます。
276.7.10 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);
パラメータ
表276-14 FRENAMEプロシージャのパラメータ
| パラメータ | 説明 |
|---|---|
|
|
ソース・ファイルのディレクトリ位置。 |
|
|
名前変更対象のソース・ファイル。 |
|
|
宛先ファイルの宛先ディレクトリ。 |
|
|
ファイルの新しい名前。 |
|
|
デフォルトは |
例外
ACCESS_DENIED
INVALID_FILENAME
INVALID_PATH
RENAME_FAILED
276.7.11 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);
パラメータ
表276-15 FSEEKプロシージャのパラメータ
| パラメータ | 説明 |
|---|---|
|
|
ファイル・ハンドル。 |
|
|
検索先の絶対位置。デフォルト= |
|
|
前方または後方に検索するバイト数。正数=前方、負の整数=後方、0(ゼロ)=現在の位置、デフォルト= |
例外
INVALID_FILEHANDLE
INVALID_OFFSET
INVALID_OPERATION
READ_ERROR
使用上のノート
-
FSEEKを使用すると、最初にファイルのクローズと再オープンを行わずに、ファイル内の前の行を読み込むことができます。ナビゲートするバイト数を把握しておく必要があります。 -
relative_offsetを使用する場合、このプロシージャは前方検索(relative_offset> 0の場合)、または後方検索(relative_offset< 0の場合)を行い、指定されたrelative_offsetバイトの数のみファイルを検索します。 -
指定されたバイト数に至る前にファイルの先頭まで到達した場合、ファイル・ポインタはファイルの先頭に置かれます。指定されたバイト数に至る前にファイルの終わりに達した場合、
INVALID_OFFSETエラーが発生します。 -
absolute_offsetの場合、このプロシージャは、バイト数で指定された絶対位置を検索します。 -
ファイルがバイト・モード操作用にオープンしている場合は、
INVALIDOPERATION例外が発生します。
276.7.12 GET_LINEプロシージャ
このプロシージャは、ファイル・ハンドルが示すオープン・ファイルからテキストを1行読み込んで、出力バッファ・パラメータに配置します。テキストは、ファイルまたはlenパラメータの最後まで読み込まれますが、行の終了記号は含まれません。FOPENに指定されているmax_linesizeを超えることはできません。
構文
UTL_FILE.GET_LINE ( file IN FILE_TYPE, buffer OUT VARCHAR2, len IN PLS_INTEGER DEFAULT NULL);
パラメータ
表276-16 GET_LINEプロシージャのパラメータ
| パラメータ | 説明 |
|---|---|
|
|
ファイルは読込み用(モード |
|
|
ファイルから読み込まれた行を受け取るデータ・バッファ。 |
|
|
ファイルから読み込むバイト数。デフォルトは |
例外
INVALID_FILEHANDLE
INVALID_OPERATION
NO_DATA_FOUND
READ_ERROR
使用上のノート
行がバッファに収まらない場合は、READ_ERROR例外が発生します。ファイルの終わりに到達したためにテキストが読み込まれなかった場合は、NO_DATA_FOUND例外が発生します。ファイルがバイト・モード操作用にオープンしている場合は、INVALID_OPERATION例外が発生します。
行終了記号の文字はバッファに読み込まれないため、ブランク行を読み込むと空の文字列が戻されます。
bufferパラメータの最大サイズは、より小さいサイズをFOPENに指定しないかぎり、32767バイトです。指定しない場合は、デフォルト値の1024が設定されます。「GET_LINE_NCHARプロシージャ」も参照してください。
276.7.13 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);
パラメータ
表276-17 GET_LINE_NCHARプロシージャのパラメータ
| パラメータ | 説明 |
|---|---|
|
|
|
|
|
ファイルから読み込まれた行を受け取るデータ・バッファ。 |
|
|
ファイルから読み込むバイト数。デフォルトは |
例外
INVALID_FILEHANDLE
INVALID_OPERATION
NO_DATA_FOUND
READ_ERROR
276.7.14 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);
パラメータ
表276-18 GET_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;276.7.15 IS_OPENファンクション
このファンクションは、オープン・ファイルをファイル・ハンドルが識別しているかどうかをテストします。
IS_OPENは、ファイル・ハンドルが、オープン状態でクローズしていないファイルを示しているかどうかを通知するのみです。これは、ユーザーがファイル・ハンドルを使用しようとしたときに、オペレーティング・システムのエラーが発生しないことを保証するものではありません。
構文
UTL_FILE.IS_OPEN ( file IN FILE_TYPE) RETURN BOOLEAN;
パラメータ
表276-19 IS_OPENファンクションのパラメータ
| パラメータ | 説明 |
|---|---|
|
|
|
戻り値
TRUEまたはFALSE
例外
INVALID_FILEHANDLE
276.7.16 NEW_LINEプロシージャ
このプロシージャは、入力ファイル・ハンドルが示すファイルに、1つ以上の行終了記号を書き込みます。
行終了記号はプラットフォーム固有の文字や文字列であるため、このプロシージャはPUTとは異なります。
構文
UTL_FILE.NEW_LINE ( file IN FILE_TYPE, lines IN BINARY_INTEGER := 1);
パラメータ
表276-20 NEW_LINEプロシージャのパラメータ
| パラメータ | 説明 |
|---|---|
|
|
|
|
|
ファイルに書き込む行終了記号の数。 |
例外
INVALID_FILEHANDLE
INVALID_OPERATION
WRITE_ERROR
276.7.17 PUTプロシージャ
PUTプロシージャは、ファイル・ハンドルが示すオープン・ファイルに、バッファ・パラメータ内に格納されているテキスト文字列を書き込みます。
このファイルは書込み操作用にオープンされる必要があります。PUTは、行終了記号を追加しません。NEW_LINEを使用して行を終了するか、またはPUT_LINEを使用して行終了記号付きの完全な1行を書き込んでください。「PUT_NCHARプロシージャ」も参照してください。
構文
UTL_FILE.PUT ( file IN FILE_TYPE, buffer IN VARCHAR2);
パラメータ
表276-21 PUTプロシージャのパラメータ
| パラメータ | 説明 |
|---|---|
|
|
|
|
|
ファイルに書き込むテキストを含んだバッファ。 ファイルはモード |
使用上のノート
bufferパラメータの最大サイズは、より小さいサイズをFOPENに指定しないかぎり、32767バイトです。指定がない場合は、デフォルト値である1024が指定されます。連続したPUTコールの全合計は、途中でバッファ・フラッシュをしないかぎり、32767を超えません。
例外
INVALID_FILEHANDLE
INVALID_OPERATION
WRITE_ERROR
276.7.18 PUT_LINEプロシージャ
このプロシージャは、ファイル・ハンドルが示すオープン・ファイルに、バッファ・パラメータ内に格納されているテキスト文字列を書き込みます。
このファイルは書込み操作用にオープンされる必要があります。PUT_LINEは、プラットフォーム固有の行終了文字または文字列で行を終了します。
「PUT_LINE_NCHARプロシージャ」も参照してください。
構文
UTL_FILE.PUT_LINE ( file IN FILE_TYPE, buffer IN VARCHAR2, autoflush IN BOOLEAN DEFAULT FALSE);
パラメータ
表276-22 PUT_LINEプロシージャのパラメータ
| パラメータ | 説明 |
|---|---|
|
|
|
|
|
ファイルに書き込む行を含んだテキスト・バッファ。 |
|
|
|
例外
INVALID_FILEHANDLE
INVALID_OPERATION
WRITE_ERROR
使用上のノート
-
bufferパラメータの最大サイズは、より小さいサイズをFOPENに指定しないかぎり、32767バイトです。指定がない場合は、デフォルト値である1024が指定されます。連続したPUTコールの全合計は、途中でバッファ・フラッシュをしないかぎり、32767を超えません。 -
ファイルがバイト・モード操作用にオープンしている場合は、
INVALIDOPERATION例外が発生します。
276.7.19 PUT_LINE_NCHARプロシージャ
このプロシージャは、ファイル・ハンドルが示すオープン・ファイルに、バッファ・パラメータ内に格納されているテキスト文字列を書き込みます。このファンクションを使用すると、データベース文字セットではなくUnicodeでテキスト・ファイルの書込みを実行できます。
このプロシージャは、書き込まれたテキストに行セパレータが追加されることを除いて、PUT_NCHARプロシージャと同じです。「PUT_LINEプロシージャ」も参照してください。
構文
UTL_FILE.PUT_LINE_NCHAR ( file IN FILE_TYPE, buffer IN NVARCHAR2);
パラメータ
表276-23 PUT_LINE_NCHARプロシージャのパラメータ
| パラメータ | 説明 |
|---|---|
|
|
|
|
|
ファイルに書き込む行を含んだテキスト・バッファ。 |
例外
INVALID_FILEHANDLE
INVALID_OPERATION
WRITE_ERROR
使用上のノート
-
bufferパラメータの最大サイズは、より小さいサイズをFOPENに指定しないかぎり、32767バイトです。指定がない場合は、デフォルト値である1024が指定されます。連続したPUTコールの全合計は、途中でバッファ・フラッシュをしないかぎり、32767を超えません。 -
ファイルがバイト・モード操作用にオープンしている場合は、
INVALIDOPERATION例外が発生します。
276.7.20 PUT_NCHARプロシージャ
このプロシージャは、ファイル・ハンドルが示すオープン・ファイルに、バッファ・パラメータ内に格納されているテキスト文字列を書き込みます。
このファンクションを使用すると、データベース文字セットではなくUnicodeでテキスト・ファイルの書込みを実行できます。このファイルは、各国語文字セット・モードでオープンされる必要があります。テキスト文字列は、UTF8文字セットで書き込まれます。想定されるバッファのデータ・タイプは、NVARCHAR2です。別のデータ・タイプの変数が指定されていると、テキストの書込み前にNVARCHAR2への暗黙的な変換が実行されます。
構文
UTL_FILE.PUT_NCHAR ( file IN FILE_TYPE, buffer IN NVARCHAR2);
パラメータ
表276-24 PUT_NCHARプロシージャのパラメータ
| パラメータ | 説明 |
|---|---|
|
|
|
|
|
ファイルに書き込むテキストを含んだバッファ。 ファイルはモード |
例外
INVALID_FILEHANDLE
INVALID_OPERATION
WRITE_ERROR
使用上のノート
bufferパラメータの最大サイズは、より小さいサイズをFOPENに指定しないかぎり、32767バイトです。指定がない場合は、デフォルト値である1024が指定されます。連続したPUTコールの全合計は、途中でバッファ・フラッシュをしないかぎり、32767を超えません。
関連項目
276.7.21 PUTFプロシージャ
このプロシージャは、書式付きのPUTプロシージャです。
これは、制限付きのprintf()のように動作します。
構文
UTL_FILE.PUTF ( file IN FILE_TYPE, format IN VARCHAR2, [arg1 IN VARCHAR2 DEFAULT NULL, . . . arg5 IN VARCHAR2 DEFAULT NULL]);
パラメータ
表276-25 PUTFプロシージャのパラメータ
| パラメータ | 説明 |
|---|---|
|
|
|
|
|
テキストや書式文字 |
|
|
1から5個までのオプションの引数文字列。 引数文字列は、書式文字列内の 引数より多い書式指定文字が書式パラメータ文字列内にある場合は、引数のない各 |
使用上のノート
-
ファイルがバイト・モード操作用にオープンしている場合は、
INVALIDOPERATION例外が発生します。 -
書式文字列には任意のテキストを指定できますが、文字列
%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は空の文字列に置き換えられます。
関連項目
276.7.22 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]);
パラメータ
表276-26 PUTF_NCHARプロシージャのパラメータ
| パラメータ | 説明 |
|---|---|
|
|
|
|
|
テキストや書式文字 |
|
|
1から5個までのオプションの引数文字列。 引数文字列は、書式文字列内の%s書式指定文字に、順序正しく置き換えられます。 引数より多い書式指定文字が書式パラメータ文字列内にある場合は、引数のない各%sは空の文字列に置き換えられます。 |
例外
INVALID_FILEHANDLE
INVALID_OPERATION
WRITE_ERROR
使用上のノート
-
bufferパラメータの最大サイズは、より小さいサイズをFOPENに指定しないかぎり、32767バイトです。指定がない場合は、デフォルト値である1024が指定されます。連続したPUTコールの全合計は、途中でバッファ・フラッシュをしないかぎり、32767を超えません。 -
ファイルがバイト・モード操作用にオープンしている場合は、
INVALIDOPERATION例外が発生します。
関連項目
276.7.23 PUT_RAWプロシージャ
このプロシージャは、RAWデータ値を入力として受け入れ、出力バッファに書き込みます。
構文
UTL_FILE.PUT_RAW ( file IN UTL_FILE.FILE_TYPE, buffer IN RAW, autoflush IN BOOLEAN DEFAULT FALSE);
パラメータ
表276-27 PUT_RAWプロシージャのパラメータ
| パラメータ | 説明 |
|---|---|
|
|
ファイル・ハンドル。 |
|
|
バッファに書き込まれた |
|
|
|
例外
INVALID_FILEHANDLE
INVALID_OPERATION
WRITE_ERROR
使用上のノート
3番目の引数をTRUEに設定することで、バッファの自動フラッシュを要求できます。
bufferパラメータの最大サイズは、より小さいサイズをFOPENに指定しないかぎり、32767バイトです。指定がない場合は、デフォルト値である1024が指定されます。連続したPUTコールの全合計は、途中でバッファ・フラッシュをしないかぎり、32767を超えません。