| Oracle® TimesTen In-Memory Database PL/SQLパッケージ・リファレンス 11gリリース2 (11.2.2) B66725-05 |
|
 前 |
 次 |
UTL_FILEパッケージを使用して、PL/SQLプログラムでオペレーティング・システムのテキスト・ファイルの読込みと書込みができます。UTL_FILEは、オペレーティング・システムのストリーム・ファイルI/Oの制約付きバージョンを提供します。
この章の内容は次のとおりです。
セキュリティ・モデル
ルールおよび制限
例外
例
TimesTen 11.2.xリリースでは、UTL_FILEは、ディレクトリinstall_dir/plsql/utl_file_tempに制限されます。アクセスは、このディレクトリのサブディレクトリにまで拡張されることはありません。また、アクセスでは、ファイル・システムに対する権限チェックが行われます。必要に応じて、インスタンス管理者は、UTL_FILEアクセス権限を特定のユーザーに付与できます。ユーザーは、UTL_FILEサブプログラムのロケーション・パラメータに文字列'UTL_FILE_TEMP'を使用して、このUTL_FILEディレクトリを参照できます。この事前定義済の文字列は、Oracle Databaseのディレクトリ・オブジェクト名と同じ方法で使用されます。
UTL_FILEは、目的のアクセス制限を回避するように使用できるリンクで使用することはできません。ファイル名としてリンクを指定すると、FOPENが失敗し、エラーが発生します。
TimesTenの直接接続の場合、アプリケーション所有者がファイルの所有者です。クライアント/サーバー接続の場合、サーバー所有者がファイルの所有者です。
UTL_FILE_DIRアクセスは、TimesTenでサポートされていません。
|
重要:
|
ファイルの場所とファイル名の各パラメータは、別々の文字列として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を設定する場合は、データベースのキャラクタ・セットと同じものにする必要があります。
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パッケージの例外
| 例外名 | 説明 |
|---|---|
|
|
ファイルの場所に対するアクセス許可が拒否されました。 |
|
|
ファイルは |
|
|
要求したファイルの削除操作に失敗しました。 |
|
|
要求した操作は、ファイルがオープンしているため失敗しました。 |
|
|
PL/SQL内で不明なエラーが発生しました。 |
|
|
ファイル・ハンドルが無効です。 |
|
|
|
|
|
|
|
|
|
|
|
原因は次のいずれかです。
|
|
|
要求どおりにファイルをオープンできないか、または操作できません。 |
|
|
ファイルの場所または名前が無効です。 |
|
|
|
|
|
読取り操作中にオペレーティング・システムのエラーが発生しました。 |
|
|
要求したファイル名変更操作に失敗しました。 |
|
|
書込み操作中にオペレーティング・システムのエラーが発生しました。 |
例1
この例では、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プロシージャを使用して、ファイルの末尾にコンテンツが追加されます。
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プロシージャを使用して、指定したファイルから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の内容は、UTL_FILEパッケージ専用です。このレコードのコンポーネントを参照または変更しないでください。
TYPE file_type IS RECORD ( id BINARY_INTEGER, datatype BINARY_INTEGER, byte_mode BOOLEAN);
フィールド
表11-2 FILE_TYPEのフィールド
| フィールド | 説明 |
|---|---|
|
|
内部ファイル・ハンドル番号(数値)を示します。 |
|
|
ファイルのタイプを示します( |
|
|
ファイルがバイナリ・ファイルとしてオープンされたか、テキスト・ファイルとしてオープンされたかを示します。 |
|
重要: Oracle Databaseでは、データベース・セッション間または単一セッション内でのFILE_TYPE値の永続性は保証されていません。ファイル・ハンドルのクローン化やダミー・ファイルの使用を試みると、予測できない結果が生じる可能性があります。 |
|
注意:
|
表11-3 UTL_FILEサブプログラム
| サブプログラム | 説明 |
|---|---|
|
|
ファイルをクローズします。 |
|
|
オープンしているファイル・ハンドルをすべてクローズします。 |
|
|
ファイルの連続部分を新規に作成したファイルにコピーします。 |
|
|
保留中のすべての出力を物理的にファイルに書き込みます。 |
|
|
ディスク・ファイルの属性を読み込んで戻します。 |
|
|
ファイル内の現行の相対オフセット位置をバイト数で戻します。 |
|
|
入力用または出力用にファイルをオープンします。 |
|
|
入力用または出力用にファイルをUnicodeでオープンします。 |
|
|
ユーザーに十分な権限がある場合、ディスク・ファイルを削除します。 |
|
|
UNIXの |
|
|
指定したバイトの数だけ、ファイル内でポインタを前方または後方に調整します。 |
|
|
オープンしているファイルからテキストを読み込みます。 |
|
|
オープンしているファイルからテキストをUnicodeで読み込みます。 |
|
|
|
|
|
ファイル・ハンドルが、オープンしているファイルを参照しているかどうかを判別します。 |
|
|
1つ以上のOS固有の行終了記号をファイルに書き込みます。 |
|
|
ファイルに1つの文字列を書き込みます。 |
|
|
ファイルに1行書き込み、それによってOS固有の行終了記号を1つ追加します。 |
|
|
ファイルにUnicode行を1行書き込みます。 |
|
|
ファイルに1つのUnicode文字列を書き込みます。 |
|
|
|
|
|
これは、 |
|
|
これは、 |
このプロシージャは、ファイル・ハンドルが示すオープン・ファイルをクローズします。
構文
UTL_FILE.FCLOSE (
file IN OUT UTL_FILE.FILE_TYPE);
パラメータ
例外
これらの例外については、「例外」を参照してください。
INVALID_FILEHANDLE WRITE_ERROR
FCLOSEの実行時に、まだ書き込んでいないデータがバッファに残っていると、ファイルのクローズ時にWRITE_ERRORを受け取る場合があります。
例
「例」を参照してください。
このプロシージャは、セッションでオープンしているすべてのファイル・ハンドルをクローズします。これは、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]);
パラメータ
表11-5 FCOPYプロシージャのパラメータ
| パラメータ | 説明 |
|---|---|
|
|
ソース・ファイルのディレクトリ位置。 |
|
|
コピー対象のソース・ファイル。 |
|
|
宛先ファイルが作成される宛先ディレクトリ。 |
|
|
ソース・ファイルから作成された宛先ファイル。 |
|
|
コピー操作を開始する行の番号。 デフォルトは、最初の行の |
|
|
コピー操作を停止する行の番号。 デフォルトは、ファイルの最後を示す |
例外
これらの例外については、「例外」を参照してください。
INVALID_FILENAME INVALID_PATH INVALID_OPERATION INVALID_OFFSET READ_ERROR WRITE_ERROR
FFLUSHは、ファイル・ハンドルが示すファイルに、保留中のデータを物理的に書き込みます。ファイルに書き込むデータは通常バッファリングされます。FFLUSHプロシージャは、バッファリングされているデータを強制的にファイルに書き込みます。データは改行文字で終了する必要があります。
フラッシュは、まだオープンしているファイルを読み込む必要がある場合に役立ちます。たとえば、デバッグ・メッセージをファイルにフラッシュして、即時に読み込むことができます。
構文
UTL_FILE.FFLUSH (
file IN UTL_FILE.FILE_TYPE);
パラメータ
例外
これらの例外については、「例外」を参照してください。
INVALID_FILEHANDLE INVALID_OPERATION WRITE_ERROR
例
「例」を参照してください。
このプロシージャは、ディスク・ファイルの属性を読み込んで戻します。
構文
UTL_FILE.FGETATTR( location IN VARCHAR2, filename IN VARCHAR2, fexists OUT BOOLEAN, file_length OUT NUMBER, block_size OUT BINARY_INTEGER);
パラメータ
表11-7 FGETATTRプロシージャのパラメータ
| パラメータ | 説明 |
|---|---|
|
|
ソース・ファイルの位置 |
|
|
検証されるファイルの名前。 |
|
|
ファイルが存在するかどうかを示す |
|
|
バイト単位でのファイルの長さ、またはファイルが存在しない場合は |
|
|
バイト単位でのファイル・システムのブロック・サイズ、またはファイルが存在しない場合は |
例外
これらの例外については、「例外」を参照してください。
INVALID_PATH INVALID_FILENAME INVALID_OPERATION READ_ERROR ACCESS_DENIED
このファンクションは、ファイル内の現行の相対オフセット位置をバイト数で戻します。
構文
UTL_FILE.FGETPOS (
file IN utl_file.file_type)
RETURN BINARY_INTEGER;
パラメータ
戻り値
オープン・ファイルのバイト単位での相対的なオフセット位置、またはファイルの先頭の場合は0
例外
これらの例外については、「例外」を参照してください。
INVALID_FILEHANDLE INVALID_OPERATION READ_ERROR
ファイルがオープンしていない場合は、INVALID_FILEHANDLE例外が発生します。ファイルがバイト・モード操作用にオープンしていた場合は、INVALID_OPERATION例外が発生します。
このファンクションは、ファイルをオープンします。最大行サイズを指定でき、最大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ファンクション・パラメータ
| パラメータ | 説明 |
|---|---|
|
|
ファイルのディレクトリ位置。 |
|
|
拡張子(ファイル・タイプ)も含めたファイル名で、ディレクトリ・パスはありません ディレクトリ・パスがファイル名の一部として指定される場合も、 |
|
|
ファイルがオープンしたモード
|
|
|
改行文字を含むこのファイルの1行当たりの最大文字数 最小値は1、最大値は32767です。指定しない場合は、デフォルト値の1024が設定されます。 |
戻り値
そのファイルを操作する後続プロシージャすべてに渡す必要のあるファイル・ハンドル
ファイル・ハンドルの特定の内容は、UTL_FILEパッケージ専用であり、UTL_FILEのユーザーは、個々のコンポーネントの参照または変更を行わないでください。
使用上の注意
ファイルの場所とファイル名の各パラメータは、別々の文字列としてFOPENファンクションに指定されるため、ファイルの場所は、utl_file_tempディレクトリと照合してチェックできます。ファイルの場所と名前は、システム上の有効なファイル名である必要があり、ディレクトリはアクセス可能である必要があります。utl_file_tempのサブディレクトリにはアクセスできません。
例外
これらの例外については、「例外」を参照してください。
INVALID_PATH INVALID_MODE INVALID_OPERATION INVALID_MAXLINESIZE
例
「例」を参照してください。
このファンクションは、指定した最大行サイズで入力用または出力用ファイルを各国語キャラクタ・セット・モードでオープンします。最大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ファンクションのパラメータ
| パラメータ | 説明 |
|---|---|
|
|
ファイルのディレクトリ位置。 |
|
|
拡張子も含めたファイル名 |
|
|
ファイルをオープンするモード: |
|
|
改行文字を含むこのファイルの1行当たりの最大文字数 最小値は1、最大値は32767です。指定しない場合は、デフォルト値の1024が設定されます。 |
戻り値
そのファイルを操作する後続プロシージャすべてに渡す必要のあるファイル・ハンドル
ファイル・ハンドルの特定の内容は、UTL_FILEパッケージ専用であり、UTL_FILEのユーザーは、個々のコンポーネントの参照または変更を行わないでください。
例外
これらの例外については、「例外」を参照してください。
INVALID_PATH INVALID_MODE INVALID_OPERATION INVALID_MAXLINESIZE
このプロシージャは、ユーザーに十分な権限がある場合に、ディスク・ファイルを削除します。
構文
UTL_FILE.FREMOVE ( location IN VARCHAR2, filename IN VARCHAR2);
パラメータ
使用上の注意
このプロシージャでは、ファイルを削除する前に権限の有無を検証しません。ファイルとディレクトリに対するアクセス権限は、オペレーティング・システムによって検証されます。
例外
これらの例外については、「例外」を参照してください。
INVALID_PATH INVALID_FILENAME INVALID_OPERATION ACCESS_DENIED DELETE_FAILED
このプロシージャは、既存のファイルの名前を変更します。
構文
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プロシージャのパラメータ
| パラメータ | 説明 |
|---|---|
|
|
ソース・ファイルのディレクトリ位置。 |
|
|
名前変更対象のソース・ファイル。 |
|
|
宛先ファイルの宛先ディレクトリ |
|
|
ファイルの新しい名前。 |
|
|
宛先ディレクトリ内の既存のファイルの上書きを許可するかどうか(デフォルト: |
使用上の注意
ソース・ディレクトリと宛先ディレクトリの両方に対するアクセス権限の付与が必要です。
例外
これらの例外については、「例外」を参照してください。
INVALID_PATH INVALID_FILENAME RENAME_FAILED ACCESS_DENIED
このプロシージャは、指定したバイトの数だけ、ファイル内でポインタを前方または後方に調整します。
構文
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プロシージャのパラメータ
| パラメータ | 説明 |
|---|---|
|
|
|
|
|
検索先のバイト単位での絶対位置(デフォルト= |
|
|
前方または後方に検索するバイト数 前方に検索する場合は正の整数、後方に検索する場合は負の整数、現在の位置の場合は0(ゼロ)。デフォルトは |
使用上の注意
FSEEKを使用すると、最初にファイルのクローズと再オープンを行わずに、ファイル内の前の行を読み込むことができます。ナビゲートするバイト数を把握しておく必要があります。
指定されたバイト数に至る前にファイルの先頭まで到達した場合、ファイル・ポインタはファイルの先頭に置かれます。
例外
これらの例外については、「例外」を参照してください。
INVALID_FILEHANDLE INVALID_OPERATION READ_ERROR INVALID_OFFSET
ファイルがバイト・モード操作用にオープンしていた場合は、INVALID_OPERATION例外が発生します。指定されたバイト数に至る前にファイルの終わりに達した場合は、INVALID_OFFSETエラーが発生します。
このプロシージャは、ファイル・ハンドルが示すオープン・ファイルからテキストを読み込んで、出力バッファ・パラメータに配置します。テキストは、ファイルまたは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プロシージャのパラメータ
| パラメータ | 説明 |
|---|---|
|
|
|
|
|
ファイルから読み込まれた行を受け取るデータ・バッファ。 |
|
|
ファイルから読み込むバイト数
|
使用上の注意
行終了記号の文字はバッファに読み込まれないため、ブランク行を読み込むと空の文字列が戻されます。
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例外です。)
例
「例」を参照してください。
このプロシージャは、ファイル・ハンドルが示すオープン・ファイルからテキストを読み込んで、出力バッファ・パラメータに配置します。このファンクションを使用すると、データベース・キャラクタ・セットではなく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プロシージャのパラメータ
| パラメータ | 説明 |
|---|---|
|
|
このファイルは読込み用(モード |
|
|
ファイルから読み込まれた行を受け取るデータ・バッファ。 |
|
|
ファイルから読み込むバイト数
|
例外
これらの例外については、「例外」を参照してください。
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例外です。)
このプロシージャは、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ファンクションのパラメータ
| パラメータ | 説明 |
|---|---|
|
|
|
|
|
|
|
|
ファイルから読み込むバイト数
|
例外
これらの例外については、「例外」を参照してください。
INVALID_FILEHANDLE INVALID_OPERATION READ_ERROR LENGTH_MISMATCH NO_DATA_FOUND
(NO_DATA_FOUNDは、事前定義済のPL/SQL例外です。)
例
「例」を参照してください。
このファンクションは、オープン・ファイルをファイル・ハンドルが識別しているかどうかをテストします。これは、ファイル・ハンドルが、オープン状態でクローズしていないファイルを示しているかどうかを通知するのみです。これは、エラーなしでファイルを使用できることを保証するものではありません。
構文
UTL_FILE.IS_OPEN (
file IN UTL_FILE.FILE_TYPE)
RETURN BOOLEAN;
パラメータ
戻り値
ファイルがオープンしている場合はTRUE、そうでない場合はFALSE
例外
この例外については、「例外」を参照してください。
INVALID_FILEHANDLE
このプロシージャは、入力ファイル・ハンドルが示すファイルに、1つ以上の行終了記号を書き込みます。行終了記号はプラットフォーム固有の文字や文字列であるため、このプロシージャはPUTとは異なります。
構文
UTL_FILE.NEW_LINE ( file IN UTL_FILE.FILE_TYPE, lines IN BINARY_INTEGER := 1);
パラメータ
表11-18 NEW_LINEプロシージャのパラメータ
| パラメータ | 説明 |
|---|---|
|
|
|
|
|
ファイルに書き込む行終了記号の数。 |
例外
この例外については、「例外」を参照してください。
INVALID_FILEHANDLE INVALID_OPERATION WRITE_ERROR
PUTプロシージャは、ファイル・ハンドルが示すオープン・ファイルに、バッファ・パラメータ内に格納されているテキスト文字列を書き込みます。このファイルは書込み操作用にオープンされる必要があります。PUTは、行終了記号を追加しません。行の終了にはNEW_LINEを使用するか、またはPUT_LINEを使用して行終了記号付きの完全な1行を書き込んでください。「PUT_NCHARプロシージャ」も参照してください。
構文
UTL_FILE.PUT ( file IN UTL_FILE.FILE_TYPE, buffer IN VARCHAR2);
パラメータ
表11-19 PUTプロシージャのパラメータ
| パラメータ | 説明 |
|---|---|
|
|
このファイルは書込み用(モード |
|
|
ファイルに書き込むテキストを含んだバッファ |
使用上の注意
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_NCHARプロシージャ」も参照してください。
構文
UTL_FILE.PUT_LINE ( file IN UTL_FILE.FILE_TYPE, buffer IN VARCHAR2, autoflush IN BOOLEAN DEFAULT FALSE);
パラメータ
表11-20 PUT_LINEプロシージャのパラメータ
| パラメータ | 説明 |
|---|---|
|
|
|
|
|
ファイルに書き込む行を含んだテキスト・バッファ。 |
|
|
書込みの後で、バッファをディスクにフラッシュするフラグ |
使用上の注意
bufferパラメータの最大サイズは、より小さいサイズをFOPENに指定しないかぎり、32767バイトです。指定しない場合は、デフォルト値の1024が設定されます。連続したPUTコールの全合計は、途中でバッファ・フラッシュをしないかぎり、32767を超えません。
例外
この例外については、「例外」を参照してください。
INVALID_FILEHANDLE INVALID_OPERATION WRITE_ERROR CHARSETMISMATCH
ファイルがバイト・モード操作用にオープンしている場合は、INVALID_OPERATIONがスローされます。FOPENでなくFOPEN_NCHARを使用してファイルをオープンした場合は、CHARSETMISMATCHがスローされます。
このプロシージャは、ファイル・ハンドルが示すオープン・ファイルに、バッファ・パラメータ内に格納されているテキスト文字列を書き込みます。このファンクションを使用すると、データベース・キャラクタ・セットではなくUnicodeでテキスト・ファイルの書込みを実行できます。このプロシージャは、書き込まれたテキストに行セパレータが追加されることを除いて、PUT_NCHARプロシージャと同じです。「PUT_LINEプロシージャ」も参照してください。
構文
UTL_FILE.PUT_LINE_NCHAR ( file IN UTL_FILE.FILE_TYPE, buffer IN NVARCHAR2);
パラメータ
表11-21 PUT_LINE_NCHARプロシージャのパラメータ
| パラメータ | 説明 |
|---|---|
|
|
このファイルは書込み用(モード |
|
|
ファイルに書き込む行を含んだテキスト・バッファ。 |
使用上の注意
bufferパラメータの最大サイズは、より小さいサイズをFOPENに指定しないかぎり、32767バイトです。指定しない場合は、デフォルト値の1024が設定されます。連続したPUTコールの全合計は、途中でバッファ・フラッシュをしないかぎり、32767を超えません。
例外
この例外については、「例外」を参照してください。
INVALID_FILEHANDLE INVALID_OPERATION WRITE_ERROR CHARSETMISMATCH
ファイルがバイト・モード操作用にオープンしている場合は、INVALID_OPERATIONがスローされます。FOPEN_NCHARでなくFOPENを使用してファイルをオープンした場合は、CHARSETMISMATCHがスローされます。
このプロシージャは、ファイル・ハンドルが示すオープン・ファイルに、バッファ・パラメータ内に格納されているテキスト文字列を書き込みます。
このファンクションを使用すると、データベース・キャラクタ・セットではなく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プロシージャのパラメータ
| パラメータ | 説明 |
|---|---|
|
|
|
|
|
ファイルに書き込むテキストを含んだバッファ |
使用上の注意
bufferパラメータの最大サイズは、より小さいサイズをFOPENに指定しないかぎり、32767バイトです。指定しない場合は、デフォルト値の1024が設定されます。連続したPUTコールの全合計は、途中でバッファ・フラッシュをしないかぎり、32767を超えません。
例外
この例外については、「例外」を参照してください。
INVALID_FILEHANDLE INVALID_OPERATION WRITE_ERROR CHARSETMISMATCH
モードwまたはa(書込みまたは追加)を使用してファイルをオープンしていない場合は、INVALID_OPERATIONがスローされます。FOPEN_NCHARでなくFOPENでファイルをオープンした場合は、CHARSETMISMATCHがスローされます。
このプロシージャは、RAWデータ値を入力として受け入れ、出力バッファに書き込みます。
構文
UTL_FILE.PUT_RAW ( file IN utl_file.file_type, buffer IN RAW, autoflush IN BOOLEAN DEFAULT FALSE);
パラメータ
表11-23 PUT_RAWプロシージャのパラメータ
| パラメータ | 説明 |
|---|---|
|
|
|
|
|
バッファに書き込まれた |
|
|
出力バッファに値を書き込んだ後でフラッシュを実行するフラグ(デフォルト: |
使用上の注意
autoflushにTRUEを設定することで、バッファの自動フラッシュを要求できます。
bufferパラメータの最大サイズは、より小さいサイズをFOPENに指定しないかぎり、32767バイトです。指定しない場合は、デフォルト値の1024が設定されます。連続したPUTコールの全合計は、途中でバッファ・フラッシュをしないかぎり、32767を超えません。
例外
これらの例外については、「例外」を参照してください。
INVALID_FILEHANDLE INVALID_OPERATION WRITE_ERROR
このプロシージャは、書式付きの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プロシージャのパラメータ
| パラメータ | 説明 |
|---|---|
|
|
|
|
|
テキストや書式文字 |
|
|
1から5個までのオプションの引数文字列 引数文字列は、書式文字列内の |
使用上の注意
書式文字列には任意のテキストを指定できますが、文字列%sと\nには特別な意味があります。
| 文字列 | 意味 |
|---|---|
%s |
この文字列を引数リスト内の次の引数の文字列値に置き換えます。 |
\n |
適切なプラットフォーム固有の行終了記号に置き換えます。 |
例外
これらの例外については、「例外」を参照してください。
INVALID_FILEHANDLE INVALID_OPERATION WRITE_ERROR CHARSETMISMATCH
ファイルがバイト・モード操作用にオープンしている場合は、INVALID_OPERATIONがスローされます。FOPENでなくFOPEN_NCHARを使用してファイルをオープンした場合は、CHARSETMISMATCHがスローされます。
例
「例」を参照してください。
このプロシージャは、PUT_NCHARプロシージャの書式化されたバージョンです。PUTF_NCHARを使用すると、データベース・キャラクタ・セットではなくUnicodeでテキスト・ファイルの書込みを実行できます。これは、書式要素\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プロシージャのパラメータ
| パラメータ | 説明 |
|---|---|
|
|
このファイルは読込み用(モード |
|
|
テキストや書式文字 |
|
|
1から5個までのオプションの引数文字列 引数文字列は、書式文字列内の |
使用上の注意
bufferパラメータの最大サイズは、より小さいサイズをFOPENに指定しないかぎり、32767バイトです。指定しない場合は、デフォルト値の1024が設定されます。連続したPUTコールの全合計は、途中でバッファ・フラッシュをしないかぎり、32767を超えません。
例外
これらの例外については、「例外」を参照してください。
INVALID_FILEHANDLE INVALID_OPERATION WRITE_ERROR CHARSETMISMATCH
ファイルがバイト・モード操作用にオープンしている場合は、INVALID_OPERATIONがスローされます。FOPEN_NCHARでなくFOPENでファイルをオープンした場合は、CHARSETMISMATCHがスローされます。
