69 DBMS_LOB

DBMS_LOBパッケージは、BLOB、CLOB、NCLOB、BFILEおよび一時LOBを操作するサブプログラムを提供します。 DBMS_LOBを使用すると、各LOBの特定の部分またはLOB全体に対するアクセスおよび操作ができます。

関連項目: 『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』

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

• DBMS_LOBの使用方法

  • 概要

  • セキュリティ・モデル

  • 定数

  • データ型

  • ルールおよび制限

  • 使用上の注意

  • 例外

• DBMS_LOBサブプログラムの要約

---

DBMS_LOBの使用方法

• 概要

• セキュリティ・モデル

• 定数

• データ型

• ルールおよび制限

• 使用上の注意

• 例外

---

概要

DBMS_LOBでは、BLOB、CLOBおよびNCLOBの読取りおよび変更ができます。BFILEに対しては、読取り専用操作を実行できます。LOB操作の大部分が、このパッケージによって提供されます。

---

セキュリティ・モデル

このパッケージは、SYSの下に作成する必要があります。このパッケージが提供する操作は、パッケージ所有者SYSではなく、現行のコール・ユーザーのもとで実行されます。

無名PL/SQLブロックからコールされたDBMS_LOBサブプログラムは、カレント・ユーザーの権限を使用して実行されます。 ストアド・プロシージャからコールされたDBMS_LOBサブプログラムは、そのストアド・プロシージャの所有者の権限を使用して実行されます。

ユーザーはプロシージャの作成時に、AUTHIDを設定して定義者の権限または実行者の権限のどちらを使用するのかを指示できます。次に例を示します。

CREATE PROCEDURE proc1 authid definer ...

または

CREATE PROCEDURE proc1 authid current_user ...

関連項目: AUTHIDおよび権限の詳細は、『Oracle Database PL/SQL言語リファレンス』を参照してください。

DIRECTORY機能を使用すると、BFILEに安全にアクセスできます。この機能の詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』および『Oracle Database SQL言語リファレンス』のBFILENAMEファンクションに関する項を参照してください。

一時LOBに関係するセキュリティ・モデルについては「使用上の注意」を参照してください。

---

定数

DBMS_LOBでは、次の定数が定義されます。

表69-1 DBMS_LOBの定数

定数	定義
FILE_READONLY	CONSTANT BINARY_INTEGER := 0;
LOB_READONLY	CONSTANT BINARY_INTEGER := 0;
LOB_READWRITE	CONSTANT BINARY_INTEGER := 1;
LOBMAXSIZE	CONSTANT INTEGER := 18446744073709551615;
SESSION	CONSTANT PLS_INTEGER := 10;
CALL	CONSTANT PLS_INTEGER := 12;

表69-2 DBMS_LOBのオプション・タイプ

定数	定義
OPT_COMPRESS	CONSTANT BINARY_INTEGER := 1;
OPT_ENCRYPT	CONSTANT BINARY_INTEGER := 2;
OPT_DEDUPLICATE	CONSTANT BINARY_INTEGER := 4;

表69-3 DBMS_LOBのオプション値

定数	定義
COMPRESS_OFF	CONSTANT BINARY_INTEGER := 0;
COMPRESS_ON	CONSTANT BINARY_INTEGER := 1;
ENCRYPT_OFF	CONSTANT BINARY_INTEGER := 0;
ENCRYPT_ON	CONSTANT BINARY_INTEGER := 2;
DEDUPLICATE_OFF	CONSTANT BINARY_INTEGER := 0;
DEDUPLICATE_ON	CONSTANT PLS_INTEGER := 4;

---

データ型

DBMS_LOBパッケージでは、表69-4に示すデータ型が使用されます。

表69-4 DBMS_LOBで使用されるデータ型

型	説明
BLOB	ソースまたは宛先のバイナリLOB。
RAW	ソースまたは宛先のRAWバッファ（BLOBとともに使用されます）。
CLOB	ソースまたは宛先の文字LOB（NCLOBを含みます）。
VARCHAR2	ソースまたは宛先の文字バッファ（CLOBおよびNCLOBとともに使用されます）。
INTEGER	バッファまたはLOBのサイズ、LOBへのオフセットまたはアクセス量を指定します。
BFILE	データベースの外部に格納されているラージ・バイナリ・オブジェクト。

DBMS_LOBパッケージは特別な型を定義しません。

NCLOBは、固定幅および可変幅のマルチバイト各国語キャラクタ・セットを格納するためのCLOBです。

CLOB用のDBMS_LOBサブプログラムの仕様部にある句ANY_CSを使用すると、CLOB型でCLOBまたはNCLOBロケータ変数を入力として受け入れることができます。

---

ルールおよび制限

• 一般的なルールおよび制限

• 外部ファイル（BFILE）に固有のルールと制限

• 最大LOBサイズ

• 最大バッファ・サイズ

一般的なルールおよび制限

• このパッケージにあるサブプログラムの仕様部に適用される規則は次のとおりです。

  • BLOBおよびBFILEを操作するサブプログラムのlength、offsetおよびamountパラメータは、バイト単位で指定する必要があります。

  • CLOBを操作するサブプログラムのlength、offsetおよびamountパラメータは、文字単位で指定する必要があります。

• パラメータ値の指定時に次の制限事項に従わなかった場合（またはパラメータ値を指定しなかった場合）は、INVALID_ARGVAL例外が発生します。

  1. LOBデータの開始位置からの正の絶対オフセットのみ許可されています。LOBの終了位置からの負のオフセットは許可されていません。

  2. amount、offset、newlen、nthなど、サイズおよび位置を表すパラメータには、0（ゼロ）以外の正の値のみ許可されています。SQL文字列ファンクションおよび演算子で確認される負のオフセットおよび範囲は許可されていません。

  3. offset、amount、newlen、nthの値は、いずれのDBMS_LOBサブプログラムの場合でも、最大値はlobmaxsize 18446744073709551615（2⁶⁴）です。

  4. 固定幅のマルチバイト・キャラクタで構成されるCLOBの場合、これらのパラメータの最大値は（lobmaxsize/character_width_in_bytes）文字です。

     たとえば、CLOBが次のような2バイト文字で構成されているとします。

     JA16SJISFIXED
     

     この場合のamountの最大値は次のとおりです。

     18446744073709551615/2 = 9223372036854775807
     

• PL/SQL言語仕様では、DBMS_LOBサブプログラムで使用されるRAWおよびVARCHAR2パラメータの上限は32767バイト（文字数ではありません）に規定されています。たとえば、変数を次のように宣言するとします。

  charbuf VARCHAR2(3000)
  

  この場合、charbufにはシングルバイト文字の場合は3000文字、2バイトの固定幅文字の場合は1500文字格納できます。 これは、CLOBおよびNCLOBに対してDBMS_LOBサブプログラムを使用するときに特に注意してください。

• %CHARSET句は、%CHARSETを使用するパラメータの形式が、参照先であるANY_CSパラメータの形式と一致している必要があることを示します。

  たとえば、VARCHAR2バッファ・パラメータを使用するDBMS_LOBサブプログラムでは、VARCHAR2バッファの形式はCLOBパラメータの形式と一致している必要があります。入力LOBパラメータの型がNCLOBの場合、バッファにはNCHARデータが含まれている必要があります。これに対して、入力LOBのパラメータの型がCLOBの場合、バッファにはCHARデータが含まれる必要があります。

  2つのCLOBパラメータを使用するDBMS_LOBサブプログラムの場合は、2つのCLOBパラメータの形式が同じであることが必要です。つまり、両方ともNCLOBであるか、またはCLOBであることが必要です。

• amountにoffsetを加えた値がデータベースで許可されているLOBの最大サイズを超えると、アクセス例外が発生します。

  この入力条件のもとでは、READ、COMPARE、INSTRおよびSUBSTRなどの読込みサブプログラムでは、End of Lob/Fileに達するまでデータが読み込まれます。 たとえば、BLOBまたはBFILEでのREAD操作で、ユーザーが、サイズが4GBのLOBのoffset値に3GB、amount値に2GBを指定すると、READでは1GB（4GB-3GB）バイトのみが戻されます。

• パラメータにNULLまたは無効な値が入力されると、ファンクションはNULLを戻します。宛先LOBのパラメータにNULL値が指定されると、プロシージャでは例外が発生します。

• パラメータとしてパターンが含まれている操作（COMPARE、INSTRおよびSUBSTRなど）では、patternパラメータまたは副文字列に、正規表現または特殊一致文字（SQLのLIKE演算子の%など）はサポートされていません。

• End Of LOB条件は、READプロシージャでNO_DATA_FOUND例外を使用して示されます。この例外が発生するのは、ユーザーがLOBの終了位置を超えてデータを読み込もうとしたときのみです。最後に読み込んだREADバッファは0（ゼロ）バイトです。

• LOB更新の一貫性を保つために、LOBデータを変更するプロシージャ（ミューテータ）をコールする前に、宛先LOBが含まれている行をロックする必要があります。

• 特に注記がないかぎり、offsetパラメータのデフォルト値は1です。これは、BLOBまたはBFILEデータの最初のバイト、およびCLOBまたはNCLOB値の最初の文字を示します。 amountパラメータはデフォルト値が指定されていないため、値を明示的に入力する必要があります。

• LOBを変更する任意のサブプログラム（例: APPEND、COPY、ERASE、TRIMまたはWRITE）をコールする前に、宛先内部LOBが含まれている行をロックする必要があります。これらのサブプログラムでは、LOBを含んだ行のロックは暗黙的には行われません。

外部ファイル（BFILE）に固有のルールと制限

• サブプログラムCOMPARE、INSTR、READ、SUBSTR、FILECLOSE、FILECLOSEALLおよびLOADFROMFILEは、オープン済のBFILEロケータでのみ動作します。つまり、これらのサブプログラムのコールの前に、FILEOPENコールが正常に完了している必要があります。

• ファンクションFILEEXISTS、FILEGETNAMEおよびGETLENGTHに関しては、ファイルのオープン/クローズ状態はあまり重要ではありません。ただし、ファイルが物理的に必ず存在し、ユーザーにDIRECTORYオブジェクトとそのファイルに関する適切な権限があることが必要です。

• DBMS_LOBは、BFILE操作に対する並行性制御メカニズムをサポートしません。

• クローズ処理が正しく行われていない複数のオープン・ファイルがセッションで使用されている場合は、FILECLOSEALLサブプログラムを使用してセッションでオープンされたファイルをすべてクローズし、ファイル操作を最初からやり直すことができます。

• DIRECTORYの作成者である場合、またはシステム権限がある場合、SQLのCREATE OR REPLACE、DROPおよびREVOKE文の使用には特に注意してください。

  ユーザーまたは特定のディレクトリ・オブジェクトの権限受領者がセッション内に複数のファイルをオープンしている場合は、前述のコマンドが誤ってファイル操作に影響を与える場合があります。この状況で異常終了した場合は、必ずFILECLOSEALLをコールするプログラムまたは無名ブロックを起動し、ファイルを再オープンしてファイル操作を再開してください。

• ユーザー・セッションの間にオープンされたファイルはすべて、セッション終了時に暗黙的にクローズされます。ただし、BFILEの操作の正常終了および異常終了いずれの場合も、操作終了後にファイルをクローズすることをお薦めします。

  プログラムが正常に終了した場合、ファイルを適切にクローズすることによって、セッションで同時にオープンしているファイル数は、必ずSESSION_MAX_OPEN_FILESより少なくなります。

  PL/SQLプログラムが異常終了した場合は、そのPL/SQLプログラム内でオープン中のすべてのファイルをクローズする例外ハンドラを使用する必要があります。例外が発生すると、最新の状態のBFILE変数にアクセスできるのは例外ハンドラのみであるため、この処理が必要です。

  例外によってプログラム制御がPL/SQLプログラム・ブロック外に転送されると、オープン中のBFILEへの参照はすべて失われます。 この結果、オープン・ファイル・カウントが増加し、SESSION_MAX_OPEN_FILES値を超える場合があります。

  たとえば、BFILE値の終了位置を超えてREAD操作を行い、NO_DATA_FOUND例外が発生したと想定します。

  -- This assumes a directory 'DDD' whose path is already known
  DECLARE
         fil BFILE:= bfilename('DDD', 'filename.foo');
         pos INTEGER;
         amt BINARY_INTEGER;
         buf RAW(40);
  BEGIN
         SELECT ad_graphic INTO fil FROM print_media WHERE product_id = 3106;
         dbms_lob.open(fil, dbms_lob.lob_readonly);
         amt := 40; pos := 1 + dbms_lob.getlength(fil); buf := '';
         dbms_lob.read(fil, amt, pos, buf);
         dbms_output.put_line('Read F1 past EOF: '||
             utl_raw.cast_to_varchar2(buf));
         dbms_lob.close(fil);
  END;
  
  ORA-01403: no data found
  ORA-06512: at "SYS.DBMS_LOB", line 373
  ORA-06512: at line 10
  

  例外が発生した後、BFILEロケータの変数ファイルは有効範囲外となり、その変数を使用したファイル操作は実行できなくなります。したがって、解決方法として、次のような例外ハンドラを使用します。

  DECLARE
       fil BFILE;
       pos INTEGER;
       amt BINARY_INTEGER;
       buf RAW(40);
  BEGIN
       SELECT ad_graphic INTO fil FROM print_media WHERE product_id = 3106;
       dbms_lob.open(fil, dbms_lob.lob_readonly);
       amt := 40; pos := 1 + dbms_lob.getlength(fil); buf := '';
       dbms_lob.read(fil, amt, pos, buf);
       dbms_output.put_line('Read F1 past EOF: '||
            utl_raw.cast_to_varchar2(buf));
       dbms_lob.close(fil);
       exception
       WHEN no_data_found
       THEN
         BEGIN
           dbms_output.put_line('End of File reached. Closing file');
           dbms_lob.fileclose(fil);
           -- or dbms_lob.filecloseall if appropriate 
         END;
  END;
       /
  
  Statement processed.
  End of File reached. Closing file
  

通常、DBMS_LOBを使用してPL/SQLブロック内でオープンされたファイルは、ブロックの正常終了または異常終了の前にクローズしてください。

最大LOBサイズ

データベースでサポートされているLOBの最大サイズは、LOB列が存在する表領域のブロック・サイズの2³²-1（4294967295）倍と等しくなります。これによって、最大LOBサイズの範囲は8TBから128TBまでとなります。

最大バッファ・サイズ

最大バッファ・サイズの32767バイトはmaxbufsizeによって表します。

---

使用上の注意

すべてのDBMS_LOBサブプログラムは、LOBロケータをベースにして動作します。 DBMS_LOBサブプログラムを正常に実行するためには、データベース表領域または外部ファイル・システムにすでに存在しているLOBを示す入力ロケータを用意する必要があります。 『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』の第1章も参照してください。

データベースでLOBを使用するには、最初にSQLデータ定義言語（DDL）を使用して、LOB列が含まれる表を定義する必要があります。

• 内部LOB

• 外部LOB

• 一時LOB

内部LOB

表にLOB列を定義した後、表に内部LOBを移入するには、SQLデータ操作言語（DML）を使用して、LOB列のロケータを初期化するか、または移入します。

外部LOB

外部LOB（BFILE）がLOBロケータで示されるようにするには、次のことを実行する必要があります。

• 有効な既存の物理ディレクトリを示すDIRECTORYオブジェクトが定義済であること、およびデータベースに対する読取り権限を伴った物理ファイル（追加対象のLOB）が存在していることを確認する必要があります。オペレーティング・システムでパス名の大文字と小文字が区別される場合は、必ず正しい形式でディレクトリを指定してください。

• 追加する外部LOBのDIRECTORYオブジェクトとファイル名をBFILENAMEファンクションに追加して、外部LOBのLOBロケータを作成する必要があります。

これらの作業が終了すると、指定されたLOBロケータを使用して、LOB列が含まれている行を挿入または更新できます。

LOBの定義および作成が終了すると、SELECTを実行してLOBロケータをローカルのPL/SQL LOB変数に割り当て、この変数をDBMS_LOBの入力パラメータとして使用してLOB値にアクセスできます。

これらの作業を行うための別の方法の詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』の外部LOB（BFILE）へのアクセスに関する項を参照してください。

一時LOB

データベースでは、一時LOBの定義、作成、削除、アクセスおよび更新がサポートされています。一時LOBデータは、ユーザーの一時表領域に格納されています。一時LOBはデータベースに永続的には格納されません。この目的は、主にLOBデータの変換の実行です。

一時LOBの場合は、OCI、PL/SQLまたはその他のプログラム・インタフェースを使用して作成または操作する必要があります。一時LOBは、BLOB、CLOBまたはNCLOBのいずれにもできます。

一時LOBは空の状態で作成されます。デフォルトでは一時LOBは、それが作成されたセッションの終了時にすべて削除されます。処理が途中で停止したり、データベースがクラッシュした場合、一時LOBは削除され、その領域は解放されます。

一時LOBを論理バケットにまとめてグループ化するインタフェースもあります。一時LOB用のこの論理記憶域は期間で表されます。各一時LOBには、CACHE/ NOCACHEなど、別々の記憶特性があります。セッションごとにデフォルトの記憶域があり、ユーザーが特定の期間を指定しない場合、一時LOBはこの記憶域に格納されます。さらに、期間ごとに解放操作を実行して、期間内のすべてのコンテンツを解放できます。

一時LOBに関する、読込み一貫性（CR）、取消し、バックアップ、パラレル処理またはトランザクション管理はサポートされていません。一時LOBには、CRおよびロールバックがサポートされていないため、エラーが発生した場合、ユーザーは一時LOBを解放して、最初から操作をやり直す必要があります。

CR、取消しおよびバージョンが、一時LOBに対しては生成されないため、同じ一時LOBに複数のロケータを割り当てると、パフォーマンスに影響する可能性があります。具体的には、各ロケータが一時LOBの独自のコピーを所有するためです。

別のロケータが一時LOBを指しているときに、その内容を変更する場合は、一時LOBのコピーが作成されます。この場合、変更操作が行われたロケータは、一時LOBの新しいコピーを指します。これ以降、他のロケータは、変更操作が行われたロケータと同じデータは参照しません。このような状況の場合、永続LOBでディープ・コピーは行われません。これは、CRスナップショットおよびバージョン・ページによって、ユーザーは独自のバージョンのLOBを簡単に参照できるためです。

必要な場合は、OCIのロケータへのポインタを使用し、ロケータへの複数のポインタが同じ一時LOBロケータを指すように設定することによって、擬似REF構文を取得できます。PL/SQLでは、1つの一時LOBに対して複数のロケータは使用しないでください。一時LOBロケータは、参照によって別のプロシージャに渡される可能性があります。

一時LOBは表スキーマと関連付けられていないため、行内および行外の一時LOBという概念はありません。ユーザーが一時LOBインスタンスを作成すると、エンジンによってLOBデータへのロケータが作成され戻されます。 PL/SQLのDBMS_LOBパッケージ、PRO*C、OCIおよびその他のプログラム・インタフェースは、このロケータを介して、永続LOBに対する操作と同様に一時LOBを操作します。

クライアント側の一時LOBはサポートされていません。一時LOBはすべてサーバーに常駐します。

一時LOBは、永続LOBがサポートしているEMPTY_BLOBまたはEMPTY_CLOBファンクションをサポートしません。 EMPTY_BLOBファンクションは、LOBの初期化を指定しますが、データの移入は行いません。

一時LOBインスタンスは、適切なFREETEMPORARYまたはOCIDurationEnd文でOCIまたはDBMS_LOBパッケージを使用したときのみ破棄できます。

一時LOBインスタンスは、適切なOCIおよびDBMS_LOB文を使用することによって、標準の永続内部LOBと同様にアクセスおよび変更できます。 一時LOBを永続LOBに変更するには、OCIまたはDBMS_LOBのCOPYコマンドを明示的に使用して、一時LOBを永続LOBにコピーする必要があります。

セキュリティは、LOBロケータを介して提供されます。一時LOBは、その作成ユーザーのみ参照できます。ロケータは、あるユーザーのセッションから別のユーザーのセッションに渡すことはできません。あるセッションから別のセッションにロケータを渡しても、元のセッションの一時LOBにはアクセスできません。一時LOB参照は、各ユーザー固有のセッションに限定されます。別の場所のロケータを使用するユーザーは、同じLOB IDを持つ自分のセッション内でのみLOBにアクセスできます。ユーザーがこれを試行することはお薦めしませんが、試行した場合でも他のユーザーのデータに影響を与えることはありません。

データベースは、V$TEMPORARY_LOBSと呼ばれるv$ビューにセッションごとの一時LOBを記録します。この中には、セッションごとに存在している一時LOB数に関する情報が含まれています。 V$ビューは、DBAが使用するためのものです。セッションから、データベースはどのユーザーがその一時LOBを所有しているかを判断できます。 V$TEMPORARY_LOBSをDBA_SEGMENTSと組み合せて使用すると、DBAは、セッションで一時LOB用に使用されている領域の量を把握できます。これらの表を使用すると、DBAは一時LOBが使用している一時領域の緊急クリーンアップを監視して指示できます。

一時LOBに固有の注意事項は次のとおりです。

1. DBMS_LOBのすべてのファンクションは、入力パラメータのいずれかがNULLの場合、NULLを戻します。 LOBロケータがNULLとして入力されると、DBMS_LOBのすべてのプロシージャで例外が発生します。

2. CLOBに基づく操作では、パラメータ（CLOBパラメータやVARCHAR2のバッファやパターンなど）のキャラクタ・セットIDが一致しているかどうかは検証されません。この確認はユーザーが各自で行ってください。

3. データ記憶域リソースは、DBAが異なるテンポラリ表領域を作成して制御します。必要に応じて、DBAはユーザーごとに別々のテンポラリ表領域を定義できます。

関連項目: NOCOPY構文の詳細は、『Oracle Database PL/SQL言語リファレンス』を参照してください。

---

例外

表69-5 DBMS_LOBの例外

例外	コード	説明
ACCESS_ERROR	22925	LOBに書き込むデータが多すぎます。LOBサイズは最大4GBです。
BUFFERING_ENABLED	22279	LOBバッファを有効にした状態では操作を実行できません。
INVALID_ARGVAL	21560	引数はNULL以外の有効な値であることが必要ですが、渡された引数値はNULL、無効または範囲外です。
INVALID_DIRECTORY	22287	現行の操作に使用しているディレクトリは、それが初めてアクセスされたか、または前回のアクセス以降にDBAによって変更された場合は無効です。
NO_DATA_FOUND		ループ読取り操作用のENDOFLOBのインジケータ。ハード・エラーではありません。
NOEXIST_DIRECTORY	22285	ファイルに指定されているディレクトリが存在しません。
NOPRIV_DIRECTORY	22286	ユーザーに、そのディレクトリまたはファイルの操作に必要なアクセス権限がありません。
OPEN_TOOMANY	22290	オープン・ファイル数が最大値に達しました。
OPERATION_FAILED	22288	ファイル操作に失敗しました。
QUERY_WRITE	14553	問合せまたはPDMLスレーブ内でLOB書込みを実行できません。
SECUREFILE_BADLOB	43856	SECUREFILEのみのコールで、SECUREFILE LOBタイプ以外のLOBが使用されました。
SECUREFILE_BADPARAM	43857	SECUREFILEサブプログラムに無効な引数が渡されました。
SECUREFILE_MARKERASED	43861	FRAGMENT_*操作に付けられたマークが削除されています。
SECUREFILE_OUTOFBOUNDS	43883	LOBの終わりを超えてFRAGMENT_*操作を実行しようとしました。
SECUREFILE_WRONGTYPE	43854	SECUREFILE LOBとともにのみ使用可能なサブプログラム内でBASICFILE LOBが使用されました。
UNOPENED_FILE	22289	要求された操作の実行に使用するファイルがオープンされていません。
VALUE_ERROR	6502	サブプログラムのパラメータの値が無効のため、PL/SQLエラーが発生しました。

---

DBMS_LOBサブプログラムの要約

表69-6 DBMS_LOBパッケージのサブプログラム

サブプログラム	説明
APPENDプロシージャ	ソースLOBの内容を宛先LOBに追加します。
CLOSEプロシージャ	オープンしている内部または外部LOBをクローズします。
COMPAREファンクション	2つのLOB全体、または2つのLOBの一部を比較します。
CONVERTTOBLOBプロシージャ	ソースCLOBまたはNCLOBインスタンスから、文字データを読み取り、指定した文字に変換して、変換したデータをバイナリ形式で宛先BLOBインスタンスに書き込み、新しいオフセットを戻します。
CONVERTTOCLOBプロシージャ	ソースBLOBインスタンスを取得し、指定した文字を使用して、ソース・インスタンスのバイナリ・データを文字データに変換し、文字データを宛先CLOBまたはNCLOBインスタンスに書き込み、新しいオフセットを戻します。
COPYプロシージャ	ソースLOB全体または一部を宛先LOBにコピーします。
CREATETEMPORARYプロシージャ	一時BLOBまたはCLOBおよびそれに対応する索引をユーザーのデフォルト一時表領域に作成します。
ERASEプロシージャ	LOB全体または一部を消去します。
FILECLOSEプロシージャ	ファイルをクローズします。
FILECLOSEALLプロシージャ	オープンしているファイルをすべてクローズします。
FILEEXISTSファンクション	ファイルがサーバー上に存在しているかどうかをチェックします。
FILEGETNAMEプロシージャ	ディレクトリ・オブジェクト名およびファイル名を取得します。
FILEISOPENファンクション	入力BFILEロケータを使用してファイルがオープンされたかどうかをチェックします。
FILEOPENプロシージャ	ファイルをオープンします。
FRAGMENT_DELETEプロシージャ	LOBからの長さを指定した場合、指定したオフセット位置にあるデータを削除します。
FRAGMENT_INSERTプロシージャ	指定したデータ（最大32K）を、LOB内の指定したオフセット位置に挿入します。
FRAGMENT_MOVEプロシージャ	指定したオフセット位置から新しく指定したオフセット位置に、バイト単位（BLOB）または文字単位（CLOB/NCLOB）で移動します。
FRAGMENT_REPLACEプロシージャ	指定したオフセット位置にあるデータを指定したデータ（32k以下）で置き換えます。
FREETEMPORARYプロシージャ	デフォルト一時表領域にある一時BLOBまたはCLOBを解放します。
GETCHUNKSIZEファンクション	LOB値を格納するLOBチャンクの使用領域容量を戻します。
GETLENGTHファンクション	LOB値の長さを取得します。
GETOPTIONSファンクション	特定のLOBのoption_typesフィールドに対応する設定を取得します。
GET_STORAGE_LIMITファンクション	データベース構成のLOBの記憶域制限を戻します。
INSTRファンクション	LOBにあるパターンのn番目の一致のマッチング位置を戻します。
ISOPENファンクション	LOBが入力ロケータを使用して、すでにオープンされたかどうかをチェックします。
ISTEMPORARYファンクション	ロケータが一時LOBを指しているかどうかをチェックします。
LOADBLOBFROMFILEプロシージャ	BFILEデータを内部BLOBにロードします。
LOADCLOBFROMFILEプロシージャ	BFILEデータを内部CLOBにロードします。
LOADFROMFILEプロシージャ	BFILEデータを内部LOBにロードします。
OPENプロシージャ	指定されたモードでLOB（内部、外部またはテンポラリ）をオープンします。
READプロシージャ	指定されたオフセット以降のLOBデータを読み込みます。
SETOPTIONSプロシージャ	LOB単位でCSCE機能を使用可能にして、デフォルトのLOB列設定より優先させます。
SUBSTRファンクション	指定されたオフセット以降のLOB値の一部を戻します。
TRIMプロシージャ	LOB値を指定された長さに切り捨てます。
WRITEプロシージャ	LOBの指定されたオフセット以降にデータを書き込みます。
WRITEAPPENDプロシージャ	LOBの終わり以降にバッファを書き込みます。

---

APPENDプロシージャ

このプロシージャは、ソース内部LOBの内容を宛先LOBに追加します。ソースLOB全体を追加します。

APPENDプロシージャは2種類、オーバーロードされています。

構文

DBMS_LOB.APPEND (
   dest_lob IN OUT  NOCOPY BLOB,
   src_lob  IN             BLOB);

DBMS_LOB.APPEND (
   dest_lob IN OUT  NOCOPY CLOB  CHARACTER SET ANY_CS,
   src_lob  IN             CLOB  CHARACTER SET dest_lob%CHARSET);

パラメータ

表69-7 APPENDプロシージャのパラメータ

パラメータ	説明
dest_lob	データを追加する内部LOBのロケータ
src_lob	データを読み取る内部LOBのロケータ

例外

表69-8 APPENDプロシージャの例外

例外	説明
VALUE_ERROR	ソースまたは宛先LOBのいずれかがNULLです。
QUERY_WRITE	問合せまたはPDMLスレーブ内でLOB書込みを実行できません。
BUFFERING_ENABLED	いずれかのLOBでバッファが有効になっている場合、LOBバッファを有効にした状態では操作を実行できません。

使用上の注意

オープン/クローズ・インタフェース内のLOB操作のラップは必須ではありません。操作を実行する前にLOBをオープンしなかった場合、LOB列のファンクション索引およびドメイン索引は、コール中に更新されます。ただし、操作を実行する前にLOBをオープンした場合は、トランザクションのコミットまたはロールバックを実行する前にクローズする必要があります。内部LOBがクローズされるときに、LOB列のファンクション索引およびドメイン索引が更新されます。

オープン/クローズAPI内のLOB操作をラップしなかった場合、ファンクション索引およびドメイン索引はLOBへ書き込むたびに更新されます。これにより、パフォーマンスに悪影響を及ぼす可能性があります。したがって、LOBへの書込み操作をOPENまたはCLOSE文の中に囲むことをお薦めします。

関連項目: このプロシージャの使用方法の詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください。

---

CLOSEプロシージャ

このプロシージャは、オープンしている内部または外部LOBをクローズします。

構文

DBMS_LOB.CLOSE (
   lob_loc    IN OUT NOCOPY BLOB);

DBMS_LOB.CLOSE (
   lob_loc    IN OUT NOCOPY CLOB CHARACTER SET ANY_CS);

DBMS_LOB.CLOSE (
   file_loc   IN OUT NOCOPY BFILE);

パラメータ

表69-9 CLOSEプロシージャのパラメータ

パラメータ	説明
lob_loc	LOBロケータ。詳細は、「使用上の注意」を参照してください。

例外

BFILEが存在していてもオープンしていない場合、エラーは戻されません。エラーは、LOBがオープンしていない場合に戻されます。

使用上の注意

CLOSEでは、内部または外部LOBのいずれの場合もサーバーへのラウンドトリップが必要です。内部LOBの場合、CLOSEはクローズ・コールに依存するその他のコードをトリガーし、外部LOB（BFILE）の場合は、サーバー側のオペレーティング・システム・ファイルを実際にクローズします。

オープン/クローズ・インタフェース内のすべてのLOB操作のラップは必須ではありません。ただし、LOBをオープンしている場合は、トランザクションのコミットまたはロールバックを実行する前にクローズする必要があります。クローズしない場合は、エラーが発生します。内部LOBがクローズされるときに、LOB列のファンクション索引およびドメイン索引が更新されます。

トランザクションによりオープンされたLOBをすべてクローズする前にトランザクションをコミットした場合、エラーが発生します。エラーが戻された場合、LOBのオープンは廃棄されますが、トランザクションのコミットは正常に行われます。したがって、そのトランザクションにおけるLOBおよび非LOBデータの変更はすべてコミットされますが、ドメイン索引およびファンクションベースの索引は更新されません。このような場合は、LOB列のファンクション索引およびドメイン索引を再構築する必要があります。

関連項目: このプロシージャの使用方法の詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください。

---

COMPAREファンクション

このファンクションは、2つのLOB全体、または2つのLOBの一部を比較します。

構文

DBMS_LOB.COMPARE (
   lob_1            IN BLOB,
   lob_2            IN BLOB,
   amount           IN INTEGER := DBMS_LOB.LOBMAXSIZE,
   offset_1         IN INTEGER := 1,
   offset_2         IN INTEGER := 1)
  RETURN INTEGER;

DBMS_LOB.COMPARE (
   lob_1            IN CLOB  CHARACTER SET ANY_CS,
   lob_2            IN CLOB  CHARACTER SET lob_1%CHARSET,
   amount           IN INTEGER := DBMS_LOB.LOBMAXSIZE,
   offset_1         IN INTEGER := 1,
   offset_2         IN INTEGER := 1)
  RETURN INTEGER;

DBMS_LOB.COMPARE (
   lob_1            IN BFILE,
   lob_2            IN BFILE,
   amount           IN INTEGER,
   offset_1         IN INTEGER := 1,
   offset_2         IN INTEGER := 1)
  RETURN INTEGER;

プラグマ

pragma restrict_references(COMPARE, WNDS, WNPS, RNDS, RNPS);

パラメータ

表69-10 COMPAREファンクションのパラメータ

パラメータ	説明
lob_1	最初の比較対象のLOBロケータ。
lob_2	2番目の比較対象のLOBロケータ。
amount	比較するバイト数（BLOBの場合）または文字数（CLOB/NCLOBS）。
offset_1	1番目のLOBの比較開始位置を示すオフセット（起点: 1）。バイト数または文字数で指定します。
offset_2	2番目のLOBの比較開始位置を示すオフセット（起点: 1）。バイト数または文字数で指定します。

戻り値

• INTEGER: 比較が正常に行われた場合は0（ゼロ）、それ以外の場合は0（ゼロ）以外の整数が戻されます。

• 次の場合にNULLが戻されます。

  • amount < 1

  • amount > LOBMAXSIZE

  • offset_1またはoffset_2 < 1

    • offset_1またはoffset_2 > LOBMAXSIZE

使用上の注意

比較できるのは、同じデータ型のLOB（BLOB型のLOBと他のBLOB、CLOBとCLOB、BFILEとBFILE）に限られます。BFILEの場合は、この操作を行う前に、FILEOPEN操作でファイルをあらかじめオープンしておく必要があります。

offsetおよびamountパラメータによって指定した範囲のデータがすべて完全に一致すると0（ゼロ）が戻されます。一致しない場合は0（ゼロ）以外のINTEGERが戻されます。

固定幅のnバイトのCLOBの場合は、COMPAREに対する入力amountの指定が（DBMS_LOB.LOBMAXSIZE/n）を超えると、（DBMS_LOB.LOBMAXSIZE/n）またはMax（length(clob1), length(clob2)）のサイズのうち、小さい方の範囲で文字を比較します。

例外

表69-11 BFILE操作に関するCOMPAREファンクションの例外

例外	説明
UNOPENED_FILE	ファイルが入力ロケータを使用してオープンされていません。
NOEXIST_DIRECTORY	ディレクトリが存在しません。
NOPRIV_DIRECTORY	ディレクトリに対する権限がありません。
INVALID_DIRECTORY	ディレクトリがファイルのオープン後に無効となりました。
INVALID_OPERATION	ファイルが存在しないか、またはファイルのアクセス権限がありません。
BUFFERING_ENABLED	いずれかのLOBでバッファが有効になっている場合、LOBバッファを有効にした状態では操作を実行できません。

関連項目: このプロシージャの使用方法の詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください。

---

CONVERTTOBLOBプロシージャ

このプロシージャは、ソースCLOBまたはNCLOBインスタンスから、文字データを読み取り、指定したキャラクタ・セットに変換して、変換したデータをバイナリ形式で宛先BLOBインスタンスに書き込み、新しいオフセットを戻します。このインタフェースは、ソースや宛先としての持続または一時LOBインスタンスのあらゆる組合せで使用できます。

構文

DBMS_LOB.CONVERTTOBLOB(
  dest_lob       IN OUT     NOCOPY  BLOB,
  src_clob       IN         CLOB CHARACTER SET ANY_CS,
  amount         IN         INTEGER,
  dest_offset    IN OUT     INTEGER,
  src_offset     IN OUT     INTEGER,
  blob_csid      IN         NUMBER,
  lang_context   IN OUT     INTEGER,
  warning        OUT        INTEGER);

パラメータ

表69-12 CONVERTTOBLOBプロシージャのパラメータ

パラメータ	説明
dest_lob	宛先LOBインスタンスのLOBロケータ。
src_blob	ソースLOBインスタンスのLOBロケータ。
amount	ソースLOBから変換する文字数。 LOB全体をコピーする場合は、定数DBMS_LOB.LOBMAXSIZEを渡します。他の値を渡す場合は、LOBのサイズ以下である必要があります。
dest_offset	（IN）宛先LOBの書込み開始位置を示すオフセット。バイト数で指定します。LOBの先頭から始める場合は値1を指定します。 （OUT）書込み終了位置の次の位置を示す新しいオフセット。バイト数で指定します。
src_offset	（IN）ソースLOBの読込み開始位置を示すオフセット。文字数で指定します。 （OUT）ソースLOBの読込み終了位置の次の位置を示すオフセット。文字数で示します。
blob_csid	変換データの目的とするキャラクタ・セットID。
lang_context	（IN）現行の変換に関する、シフト・ステータスなどの言語コンテキスト。 （OUT）現在の変換が実行されたときの言語コンテキスト。 この情報は、ユーザーがこの情報を使用してソース・データを失ったり、誤って解釈したりすることなく継続して変換できるようにするために戻されます。最初の変換の場合、または特に必要ない場合は、デフォルト値の0（ゼロ）を使用してください。
warning	（OUT）警告メッセージ。このパラメータは、変換時に何らかの異常が発生したことを示します。警告メッセージを確認する必要があります。 現在、発生する可能性があるのは、変換不可能な文字に関する警告のみです。これは、ソースの文字が宛先の文字に正しく変換できない場合に発生します。変換不可能な文字のかわりに、デフォルトの置換文字（'?'など）が使用されます。 このエラー・メッセージの戻り値は、DBMS_LOBパッケージの定数warn_inconvertible_charとして定義します。

使用上の注意

事前条件

CONVERTTOBLOBプロシージャをコールする前に、次の事前条件を満たしている必要があります。

• ソースと宛先の両方のLOBインスタンスが存在している。

• 宛先LOBが永続LOBの場合、行がロックされている。行をロックするには、SELECT文のFOR UPDATE句を使用して、LOBを選択します。

定数およびデフォルト

すべてのパラメータが必要です。各OUTまたはIN OUTパラメータに変数を渡す必要があります。各INパラメータに変数または値を渡す必要があります。

表69-13に各パラメータの一般的な値の要約を示します。1列目にパラメータ、2列目に一般的な値を示し、最後の列は値を渡した結果を説明しています。値によっては定数が使用されるので注意してください。このような定数は、dbmslob.sqlパッケージ仕様部ファイルに定義されています。

表69-13 DBMS_LOB.CONVERTTOBLOBの一般的な値

パラメータ	値	説明
amount	LOBMAXSIZE（IN）	ファイル全体を変換します。
dest_offset	1（IN）	先頭から開始します。
src_offset	1（IN）	先頭から開始します。
blob_csid	DEFAULT_CSID (IN)	デフォルトのCSID。ソースLOBと同じCSIDを使用します。
lang_context	DEFAULT_LANG_CTX (IN)	デフォルトの言語コンテキスト。
warning	NO_WARNING (OUT) WARN_INCONVERTIBLE_CHAR (OUT)	警告メッセージはありません。成功しました。 ソースの文字を正しく変換できません。

一般的な注意

blob_csidパラメータに宛先LOBの目的のキャラクタ・セットを指定する必要があります。blob_csidには0の値を渡せます。これを行う場合、データベースでは目的のキャラクタ・セットがソースLOBキャラクタ・セットと同じであると想定されます。

ソースおよび宛先の両方のLOBに対するオフセット、およびソースLOBからコピーする文字数を指定する必要があります。 amountおよびsrc_offset値は文字単位、dest_offsetはバイト単位です。LOB全体を変換するには、amountパラメータにLOBMAXSIZEを指定します。

例外

表69-14に、このプロシージャがスローする可能性のある例外を示します。1列目は例外の文字列を示し、2列目は例外の原因となる可能性のあるエラー条件を説明しています。

表69-14 CONVERTTOBLOBプロシージャの例外

例外	説明
VALUE_ERROR	入力パラメータのいずれかがNULLまたはINVALIDです。
INVALID_ARGVAL	次のいずれかの条件が発生しました。 - src_offsetまたはdest_offset < 1 - src_offsetまたはdest_offset > LOBMAXSIZE。 - amount < 1 - amount > LOBMAXSIZE

関連項目: アプリケーション開発でのLOBの使用方法の詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください。

---

CONVERTTOCLOBプロシージャ

このプロシージャは、ソースBLOBインスタンスを取得し、指定したキャラクタ・セットを使用して、ソース・インスタンスのバイナリ・データを文字データに変換し、文字データを宛先CLOBまたはNCLOBインスタンスに書き込み、新しいオフセットを戻します。このインタフェースは、ソースや宛先としての持続または一時LOBインスタンスのあらゆる組合せで使用できます。

構文

DBMS_LOB.CONVERTTOCLOB(
   dest_lob       IN OUT NOCOPY  CLOB CHARACTER SET ANY_CS,
   src_blob       IN             BLOB,
   amount         IN             INTEGER,
   dest_offset    IN OUT         INTEGER,
   src_offset     IN OUT         INTEGER,
   blob_csid      IN             NUMBER,
   lang_context   IN OUT         INTEGER,
   warning        OUT            INTEGER);

パラメータ

表69-15 CONVERTTOCLOBプロシージャのパラメータ

パラメータ	説明
dest_lob	宛先LOBインスタンスのLOBロケータ。
src_blob	ソースLOBインスタンスのLOBロケータ。
amount	ソースLOBから変換するバイト数。 BLOB全体をコピーする場合は、定数DBMS_LOB.LOBMAXSIZEを渡します。他の値を渡す場合は、BLOBのサイズ以下である必要があります。
dest_offset	（IN）宛先LOBの書込み開始位置を示すオフセット。文字数で指定します。LOBの先頭から始める場合は値1を指定します。 （OUT）書込み終了位置の次の位置を示す新しいオフセット。文字数で指定します。このオフセットは、常に書込み終了後の最初の完全な文字の開始位置を示します。
src_offset	（IN）ソースLOBの読込み開始位置を示すオフセット。バイト数で指定します。 （OUT）ソースLOBの読込み終了位置の次の位置を示すオフセット。バイト数で示します。
blob_csid	ソース・データのキャラクタ・セットID。
lang_context	（IN）現行の変換に関する、シフト・ステータスなどの言語コンテキスト。 （OUT）現在の変換が実行されたときの言語コンテキスト。 この情報は、ユーザーがこの情報を使用してソース・データを失ったり、誤って解釈したりすることなく継続して変換できるようにするために戻されます。最初の変換の場合、または特に必要ない場合は、デフォルト値の0（ゼロ）を使用してください。
warning	警告メッセージ。このパラメータは、変換時に何らかの異常が発生したことを示します。警告メッセージを確認する必要があります。 現在、発生する可能性があるのは、変換不可能な文字に関する警告のみです。これは、ソースの文字が宛先の文字に正しく変換できない場合に発生します。変換不可能な文字のかわりに、デフォルトの置換文字（'?'など）が使用されます。 このエラー・メッセージの戻り値は、DBMS_LOBパッケージの定数warn_inconvertible_charとして定義します。

使用上の注意

事前条件

CONVERTTOCLOBプロシージャをコールする前に、次の事前条件を満たしている必要があります。

• ソースと宛先の両方のLOBインスタンスが存在している。

• 宛先LOBが永続LOBの場合、CONVERTTOCLOBプロシージャをコールする前に行がロックされている。行をロックするには、SELECT文のFOR UPDATE句を使用して、LOBを選択します。

定数およびデフォルト

すべてのパラメータが必要です。各OUTまたはIN OUTパラメータに変数を渡す必要があります。各INパラメータに変数または値を渡す必要があります。

表69-16に各パラメータの一般的な値の要約を示します。1列目にパラメータ、2列目に一般的な値を示し、最後の列は値を渡した結果を説明しています。値によっては定数が使用されるので注意してください。このような定数は、dbmslob.sqlパッケージ仕様部ファイルに定義されています。

表69-16 DBMS_LOB.CONVERTTOCLOBの一般的な値

パラメータ	値	説明
amount	LOBMAXSIZE（IN）	ファイル全体を変換します。
dest_offset	1（IN）	先頭から開始します。
src_offset	1（IN）	先頭から開始します。
csid	DEFAULT_CSID (IN)	デフォルトのCSID。宛先のCSIDを使用します。
lang_context	DEFAULT_LANG_CTX (IN)	デフォルトの言語コンテキスト。
warning	NO_WARNING (OUT) WARN_INCONVERTIBLE_CHAR (OUT)	警告メッセージはありません。成功しました。 ソースの文字を正しく変換できません。

一般的な注意

blob_csidパラメータで、ソース・データのキャラクタ・セットを指定する必要があります。blob_csidには0の値を渡せます。これを行う場合、データベースではBLOB内の文字データが宛先CLOBと同じキャラクタ・セットであると想定されます。

ソースおよび宛先の両方のLOBに対するオフセット、およびソースLOBからコピーするバイト数を指定する必要があります。 amountおよびsrc_offset値はバイト単位、dest_offsetは文字単位です。BLOB全体を変換するには、amountパラメータにLOBMAXSIZEを指定します。

例外

表69-17 CONVERTTOCLOBプロシージャの例外

例外	説明
VALUE_ERROR	入力パラメータのいずれかがNULLまたはINVALIDです。
INVALID_ARGVAL	次のいずれかの条件が発生しました。 - src_offsetまたはdest_offset < 1 - src_offsetまたはdest_offset > LOBMAXSIZE。 - amount < 1 - amount > LOBMAXSIZE

関連項目: アプリケーション開発でのLOBの使用方法の詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください。

---

COPYプロシージャ

このプロシージャは、ソース内部LOBの全体または一部を宛先内部LOBにコピーします。ソースおよび宛先の両方のLOBに対するオフセット、およびコピーするバイト数または文字数を指定できます。

構文

DBMS_LOB.COPY (
  dest_lob    IN OUT NOCOPY BLOB,
  src_lob     IN            BLOB,
  amount      IN            INTEGER,
  dest_offset IN            INTEGER := 1,
  src_offset  IN            INTEGER := 1);

DBMS_LOB.COPY (
  dest_lob    IN OUT NOCOPY CLOB  CHARACTER SET ANY_CS,
  src_lob     IN            CLOB  CHARACTER SET dest_lob%CHARSET,
  amount      IN            INTEGER,
  dest_offset IN            INTEGER := 1,
  src_offset  IN            INTEGER := 1);

パラメータ

表69-18 COPYプロシージャのパラメータ

パラメータ	説明
dest_lob	コピー先のLOBロケータ。
src_lob	コピー元のLOBロケータ。
amount	コピーするバイト数（BLOBの場合）または文字数（CLOBの場合）。
dest_offset	宛先LOBのコピー開始位置を示すオフセット（起点: 1）。バイト数または文字数で指定します。
src_offset	ソースLOBのコピー開始位置を示すオフセット（起点: 1）。バイト数または文字数で指定します。

例外

表69-19 COPYプロシージャの例外 

例外	説明
VALUE_ERROR	入力パラメータのいずれかがNULLまたは無効です。
INVALID_ARGVAL	次のいずれかです。 - src_offsetまたはdest_offset < 1 - src_offsetまたはdest_offset > LOBMAXSIZE - amount < 1 - amount > LOBMAXSIZE
QUERY_WRITE	問合せまたはPDMLスレーブ内でLOB書込みを実行できません。
BUFFERING_ENABLED	いずれかのLOBでバッファが有効になっている場合、LOBバッファを有効にした状態では操作を実行できません。

使用上の注意

宛先LOBに指定したオフセットが、現在そのLOBに格納されているデータの終わりを超えている場合は、宛先BLOBまたはCLOBに、0（ゼロ）バイトのFILLERまたは空白がそれぞれ挿入されます。オフセットが宛先LOBの現行の長さより小さい場合、既存のデータは上書きされます。

ソースLOBのデータ長を超える量を指定してもエラーにはなりません。 したがって、ソースLOBのデータを、src_offsetからソースLOBの終わりまでコピーする大量のコピーを指定できます。

オープン/クローズ・インタフェース内のLOB操作のラップは必須ではありません。操作を実行する前にLOBをオープンしなかった場合、LOB列のファンクション索引およびドメイン索引は、コール中に更新されます。ただし、操作を実行する前にLOBをオープンした場合は、トランザクションのコミットまたはロールバックを実行する前にクローズする必要があります。内部LOBがクローズされるときに、LOB列のファンクション索引およびドメイン索引が更新されます。

オープン/クローズAPI内のLOB操作をラップしなかった場合、ファンクション索引およびドメイン索引はLOBへ書き込むたびに更新されます。これにより、パフォーマンスに悪影響を及ぼす可能性があります。したがって、LOBへの書込み操作をOPENまたはCLOSE文の中に囲むことをお薦めします。

関連項目: このプロシージャの使用方法の詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください。

---

CREATETEMPORARYプロシージャ

このプロシージャは、一時BLOBまたはCLOBおよびそれに対応する索引をユーザーのデフォルト一時表領域に作成します。

構文

DBMS_LOB.CREATETEMPORARY (
   lob_loc IN OUT NOCOPY BLOB,
   cache   IN            BOOLEAN,
   dur     IN            PLS_INTEGER := DBMS_LOB.SESSION);

DBMS_LOB.CREATETEMPORARY (
   lob_loc IN OUT NOCOPY CLOB CHARACTER SET ANY_CS,
   cache   IN            BOOLEAN,
   dur     IN            PLS_INTEGER := 10);

パラメータ

表69-20 CREATETEMPORARYプロシージャのパラメータ

パラメータ	説明
lob_loc	LOBロケータ。詳細は、「使用上の注意」を参照してください。
cache	LOBをバッファ・キャッシュに読み込むかどうかを指定します。
dur	3つの事前定義の継続時間（SESSION、TRANSACTIONまたはCALL）のうちの1つ。一時LOBのクリーンアップをセッション終了時に行うか、コール終了時に行うかを指定します。 durが省略された場合は、セッション継続時間が使用されます。

関連項目: このプロシージャの使用方法の詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください。 NOCOPYの詳細および一時LOBをパラメータとして渡す方法の詳細は、『Oracle Database PL/SQL言語リファレンス』を参照してください。

---

ERASEプロシージャ

このプロシージャは、内部LOB全体、または内部LOBの一部を消去します。

構文

DBMS_LOB.ERASE (
   lob_loc           IN OUT   NOCOPY   BLOB,
   amount            IN OUT   NOCOPY   INTEGER,
   offset            IN                INTEGER := 1);

DBMS_LOB.ERASE (
   lob_loc           IN OUT   NOCOPY   CLOB CHARACTER SET ANY_CS,
   amount            IN OUT   NOCOPY   INTEGER,
   offset            IN                INTEGER := 1);

パラメータ

表69-21 ERASEプロシージャのパラメータ

パラメータ	説明
lob_loc	消去するLOBのロケータ。詳細は「使用上の注意」を参照してください。
amount	消去するバイト数（BLOBまたはBFILESの場合）または文字数（CLOBまたはNCLOBの場合）。
offset	LOBの先頭からの絶対オフセット（起点: 1）。BLOBの場合はバイト数、CLOBの場合は文字数で指定します。

使用上の注意

注意: LOBの長さは、LOBのセクションを消去しても減りません。LOB値の長さを減らす方法は、「TRIMプロシージャ」を参照してください。

LOBの中央部のデータが消去されると、BLOBまたはCLOBには、0（ゼロ）バイトのFILLERまたは空白がそれぞれ書き込まれます。

指定した数だけ消去する前にLOB値の終わりに達した場合、実際に消去されたバイト数または文字数は、amountパラメータで指定した数と異なる場合があります。実際に消去された文字数またはバイト数は、amountパラメータに戻されます。

例外

表69-22 ERASEプロシージャの例外

例外	説明
VALUE_ERROR	入力パラメータのいずれかがNULLです。
INVALID_ARGVAL	次のいずれかです。 - amount < 1またはamount > LOBMAXSIZE - offset < 1またはoffset > LOBMAXSIZE
QUERY_WRITE	問合せまたはPDMLスレーブ内でLOB書込みを実行できません。
BUFFERING_ENABLED	LOBでバッファが有効になっている場合、LOBバッファを有効にした状態では操作を実行できません。

使用上の注意

オープン/クローズ・インタフェース内のLOB操作のラップは必須ではありません。操作を実行する前にLOBをオープンしなかった場合、LOB列のファンクション索引およびドメイン索引は、コール中に更新されます。ただし、操作を実行する前にLOBをオープンした場合は、トランザクションのコミットまたはロールバックを実行する前にクローズする必要があります。内部LOBがクローズされるときに、LOB列のファンクション索引およびドメイン索引が更新されます。

オープン/クローズAPI内のLOB操作をラップしなかった場合、ファンクション索引およびドメイン索引はLOBへ書き込むたびに更新されます。これにより、パフォーマンスに悪影響を及ぼす可能性があります。したがって、LOBへの書込み操作をOPENまたはCLOSE文の中に囲むことをお薦めします。

関連項目: 「TRIMプロシージャ」 このプロシージャの使用方法の詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください。

---

FILECLOSEプロシージャ

このプロシージャは、入力ロケータによってすでにオープンされているBFILEをクローズします。

注意: データベースには、BFILEに対する読取り専用アクセスしかありません。つまり、データベースを介してBFILEに書き込むことはできません。

構文

DBMS_LOB.FILECLOSE (
    file_loc IN OUT NOCOPY BFILE);

パラメータ

表69-23 FILECLOSEプロシージャのパラメータ

パラメータ	説明
file_loc	クローズするBFILEのロケータ

例外

表69-24 FILECLOSEプロシージャの例外

例外	説明
VALUE_ERROR	file_locの入力値がNULLです。
UNOPENED_FILE	ファイルが入力ロケータを使用してオープンされていません。
NOEXIST_DIRECTORY	ディレクトリが存在しません。
NOPRIV_DIRECTORY	ディレクトリに対する権限がありません。
INVALID_DIRECTORY	ディレクトリがファイルのオープン後に無効となりました。
INVALID_OPERATION	ファイルが存在しないか、またはファイルのアクセス権限がありません。

関連項目: 「FILEOPENプロシージャ」 「FILECLOSEALLプロシージャ」 このプロシージャの使用方法の詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください。

---

FILECLOSEALLプロシージャ

このプロシージャは、セッションでオープンされたすべてのBFILEをクローズします。

構文

DBMS_LOB.FILECLOSEALL;

例外

表69-25 FILECLOSEALLプロシージャの例外

例外	説明
UNOPENED_FILE	セッションでオープンされたファイルはありません。

関連項目: 「FILEOPENプロシージャ」 「FILECLOSEプロシージャ」 このプロシージャの使用方法の詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください。

---

FILEEXISTSファンクション

このファンクションは、指定したBFILEロケータが、サーバーのファイル・システムに実際に存在しているファイルを指しているかどうかを検証します。

構文

DBMS_LOB.FILEEXISTS (
   file_loc     IN    BFILE)
  RETURN INTEGER;

プラグマ

pragma restrict_references(FILEEXISTS, WNDS, RNDS, WNPS, RNPS);

パラメータ

表69-26 FILEEXISTSファンクションのパラメータ

パラメータ	説明
file_loc	BFILEのロケータ。

戻り値

表69-27 FILEEXISTSファンクションの戻り値

戻り値	説明
0	物理ファイルが存在しません。
1	物理ファイルが存在します。

例外

表69-28 FILEEXISTSファンクションの例外

例外	説明
NOEXIST_DIRECTORY	ディレクトリが存在しません。
NOPRIV_DIRECTORY	ディレクトリに対する権限がありません。
INVALID_DIRECTORY	ディレクトリがファイルのオープン後に無効となりました。

関連項目: 「FILEISOPENファンクション」 このプロシージャの使用方法の詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください。

---

FILEGETNAMEプロシージャ

このプロシージャは、指定したBFILEロケータのディレクトリ・オブジェクトとファイル名を判別します。ロケータに割り当てられたディレクトリ・オブジェクト名とファイル名を示すのみで、物理ファイルまたはディレクトリが実際に存在しているかどうかは判別しません。

dir_aliasバッファの最大値は30で、パス名全体の最大値は2000です。

構文

DBMS_LOB.FILEGETNAME (
   file_loc   IN    BFILE,
   dir_alias  OUT   VARCHAR2,
   filename   OUT   VARCHAR2);

パラメータ

表69-29 FILEGETNAMEプロシージャのパラメータ

パラメータ	説明
file_loc	BFILEのロケータ。
dir_alias	ディレクトリ・オブジェクト名
filename	BFILE名

例外

表69-30 FILEGETNAMEプロシージャの例外

例外	説明
VALUE_ERROR	入力パラメータのいずれかがNULLまたはINVALIDです。
INVALID_ARGVAL	dir_aliasまたはファイル名がNULLです。

関連項目: このプロシージャの使用方法の詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください。

---

FILEISOPENファンクション

このファンクションは、BFILEが特定のFILEロケータでオープンされたかどうかを検証します。

構文

DBMS_LOB.FILEISOPEN (
   file_loc   IN    BFILE)
  RETURN INTEGER;

プラグマ

PRAGMA RESTRICT_REFERENCES(fileisopen, WNDS, RNDS, WNPS, RNPS);

パラメータ

表69-31 FILEISOPENファンクションのパラメータ

パラメータ	説明
file_loc	BFILEのロケータ。

戻り値

INTEGER: 0 =ファイルはオープンされていません。1 =ファイルはオープンされています。

使用上の注意

入力FILEロケータがFILEOPENプロシージャに渡されていない場合、そのファイルはこのロケータによってオープンされていないとみなされます。ただし、別のロケータがこのファイルをオープンしている可能性はあります。つまり、オープンされているかどうかは特定のロケータと関連付けられています。

例外

表69-32 FILEISOPENファンクションの例外

例外	説明
NOEXIST_DIRECTORY	ディレクトリが存在しません。
NOPRIV_DIRECTORY	ディレクトリに対する権限がありません。
INVALID_DIRECTORY	ディレクトリがファイルのオープン後に無効となりました。

関連項目: 「FILEEXISTSファンクション」 このプロシージャの使用方法の詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください。

---

FILEOPENプロシージャ

このプロシージャは、BFILEを読取り専用アクセスでオープンします。データベースを介してBFILEに書き込むことはできません。

構文

DBMS_LOB.FILEOPEN (
   file_loc   IN OUT NOCOPY  BFILE,
   open_mode  IN             BINARY_INTEGER := file_readonly);

パラメータ

表69-33 FILEOPENプロシージャのパラメータ

パラメータ	説明
file_loc	BFILEのロケータ。
open_mode	ファイル・アクセスは読取り専用です。

例外

表69-34 FILEOPENプロシージャの例外

例外	説明
VALUE_ERROR	file_locまたはopen_modeがNULLです。
INVALID_ARGVAL	open_modeがFILE_READONLYではありません。
OPEN_TOOMANY	セッション内のオープン・ファイル数がsession_max_open_filesを超えています。
NOEXIST_DIRECTORY	file_locに関連付けられたディレクトリが存在しません。
INVALID_DIRECTORY	ディレクトリがファイルのオープン後に無効となりました。
INVALID_OPERATION	ファイルが存在しないか、またはファイルのアクセス権限がありません。

関連項目: 「FILECLOSEプロシージャ」 「FILECLOSEALLプロシージャ」 このプロシージャの使用方法の詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください。

---

FRAGMENT_DELETEプロシージャ

このプロシージャは、LOBからの長さを指定した場合、指定したオフセット位置にあるデータを削除します。LOB内の指定したオフセット位置の後にあるすべてのデータをリライトする必要はありません。

構文

DBMS_LOB.FRAGMENT_DELETE (
   lob_loc     IN OUT NOCOPY BLOB,
   amount      IN            INTEGER,
   offset      IN            INTEGER);

DBMS_LOB.FRAGMENT_DELETE (
   lob_loc     IN OUT NOCOPY CLOB CHARACTER SET ANY_CS,
   amount      IN            INTEGER,
   offset      IN            INTEGER);

パラメータ

表69-35 FRAGMENT_DELETEプロシージャのパラメータ

パラメータ	説明
lob_loc	LOBロケータ。詳細は、「使用上の注意」を参照してください。
amount	LOBから削除するバイト数（BLOB）または文字数（CLOB/NCLOB）。
offset	削除を開始するLOB内のオフセット位置を示すバイト数（BLOB）または文字数（CLOB/NCLOB）。

例外

表69-36 FRAGMENT_DELETEプロシージャの例外

例外	説明
SECUREFILE_BADLOB	操作に対してサポートされていないオブジェクト・タイプ。
INVALID_ARGVAL	パラメータ値が無効でした。
QUERY_WRITE	問合せ時に操作を実行できません。
BUFFERING_ENABLED	LOBバッファを有効にした状態では操作を実行できません。
SECUREFILE_BADLOB	SECUREFILE LOBのみのコールで、SECUREFILE以外のLOBが使用されました。
SECUREFILE_OUTOFBOUNDS	LOBの終わりを超えてFRAGMENT_*操作を実行しようとしました。
SECUREFILE_WRONGTYPE	SECUREFILE LOBのみのコールで、BASICFILE LOBが使用されました。

---

FRAGMENT_INSERTプロシージャ

このファンクションは、指定したデータ（最大32K）を、LOB内の指定したオフセット位置に挿入します。

構文

DBMS_LOB.FRAGMENT_INSERT (
   lob_loc     IN OUT NOCOPY BLOB,
   amount      IN            INTEGER,
   offset      IN            INTEGER,
   buffer      IN            RAW);

DBMS_LOB.FRAGMENT_INSERT (
   lob_loc     IN OUT NOCOPY CLOB CHARACTER SET ANY_CS,
   amount      IN            INTEGER,
   offset      IN            INTEGER,
   buffer      IN            VARCHAR2 CHARACTER SET lob_loc%CHARSET);

パラメータ

表69-37 FRAGMENT_INSERTプロシージャのパラメータ

パラメータ	説明
lob_loc	LOBロケータ。詳細は、「使用上の注意」を参照してください。
amount	LOBに挿入するバイト数（BLOB）または文字数（CLOB/NCLOB）。
offset	挿入を開始するLOB内のオフセット位置を示すバイト数（BLOB）または文字数（CLOB/NCLOB）。
buffer	LOBに挿入するデータ。

例外

表69-38 FRAGMENT_INSERTプロシージャの例外

例外	説明
SECUREFILE_BADLOB	操作に対してサポートされていないオブジェクト・タイプ。
INVALID_ARGVAL	パラメータ値が無効でした。
QUERY_WRITE	問合せ時に操作を実行できません。
BUFFERING_ENABLED	LOBバッファを有効にした状態では操作を実行できません。
SECUREFILE_BADLOB	SECUREFILE LOBのみのコールで、SECUREFILE以外のLOBが使用されました。
SECUREFILE_OUTOFBOUNDS	LOBの終わりを超えてFRAGMENT_*操作を実行しようとしました。
SECUREFILE_WRONGTYPE	SECUREFILE LOBのみのコールで、BASICFILE LOBが使用されました。

---

FRAGMENT_MOVEプロシージャ

このプロシージャは、指定したオフセット位置から新しく指定したオフセット位置に、バイト単位（BLOB）または文字単位（CLOB/NCLOB）で移動します。

構文

DBMS_LOB.FRAGMENT_MOVE (
   lob_loc       IN OUT NOCOPY BLOB,
   amount        IN            INTEGER,
   src_offset    IN            INTEGER,
   dest_offset   IN            INTEGER);

DBMS_LOB.FRAGMENT_MOVE (
   lob_loc       IN OUT NOCOPY CLOB CHARACTER SET ANY_CS,
   amount        IN            INTEGER,
   src_offset    IN            INTEGER,
   dest_offset   IN            INTEGER);

パラメータ

表69-39 FRAGMENT_MOVEプロシージャのパラメータ

パラメータ	説明
lob_loc	LOBロケータ。詳細は、「使用上の注意」を参照してください。
amount	LOB内の移動するバイト数（BLOB）または文字数（CLOB/NCLOB）。
src_offset	データの挿入を開始するLOB内のオフセット位置を示すバイト数（BLOB）または文字数（CLOB/NCLOB）。
dest_offset	データの削除を開始するLOB内のオフセット位置を示すバイト数（BLOB）または文字数（CLOB/NCLOB）。

例外

表69-40 FRAGMENT_MOVEプロシージャの例外

例外	説明
SECUREFILE_BADLOB	操作に対してサポートされていないオブジェクト・タイプ。
INVALID_ARGVAL	パラメータ値が無効でした。
QUERY_WRITE	問合せ時に操作を実行できません。
BUFFERING_ENABLED	LOBバッファを有効にした状態では操作を実行できません。
SECUREFILE_BADLOB	SECUREFILE LOBのみのコールで、SECUREFILE以外のLOBが使用されました。
SECUREFILE_OUTOFBOUNDS	LOBの終わりを超えてFRAGMENT_*操作を実行しようとしました。
SECUREFILE_WRONGTYPE	SECUREFILE LOBのみのコールで、BASICFILE LOBが使用されました。

使用上の注意

• すべてのオフセット位置は事前移動オフセット位置です。

• LOBの終わりを2以上超えてオフセット位置を設定することはできません。

---

FRAGMENT_REPLACEプロシージャ

このプロシージャは、指定したオフセット位置にあるデータを指定したデータ（32k以下）で置き換えます。

構文

DBMS_LOB.FRAGMENT_REPLACE (
   lob_loc     IN OUT NOCOPY BLOB,
   old_amount  IN            INTEGER,
   new_amount  IN            INTEGER,
   offset      IN            INTEGER,
   buffer      IN            RAW);

DBMS_LOB.FRAGMENT_REPLACE (
   lob_loc     IN OUT NOCOPY CLOB CHARACTER SET ANY_CS,   old_amount  IN           INTEGER,
   new_amount  IN           INTEGER,
   offset      IN           INTEGER,
   buffer      IN           VARCHAR2 CHARACTER SET lob_loc%CHARSET);

パラメータ

表69-41 FRAGMENT_REPLACEプロシージャのパラメータ

パラメータ	説明
lob_loc	LOBロケータ。詳細は、「使用上の注意」を参照してください。
old_amount	LOB内で置き換えるバイト数（BLOB）または文字数（CLOB/NCLOB）。
new_amount	LOBに書き込むバイト数（BLOB）または文字数（CLOB/NCLOB）。
offset	データの挿入を開始するLOB内のオフセット位置を示すバイト数（BLOB）または文字数（CLOB/NCLOB）。
buffer	LOBに挿入するデータ。

例外

表69-42 FRAGMENT_REPLACEプロシージャの例外

例外	説明
SECUREFILE_BADLOB	操作に対してサポートされていないオブジェクト・タイプ。
INVALID_ARGVAL	パラメータ値が無効でした。
QUERY_WRITE	問合せ時に操作を実行できません。
BUFFERING_ENABLED	LOBバッファを有効にした状態では操作を実行できません。
SECUREFILE_BADLOB	SECUREFILE LOBのみのコールで、SECUREFILE以外のLOBが使用されました。
SECUREFILE_OUTOFBOUNDS	LOBの終わりを超えてFRAGMENT_*操作を実行しようとしました。
SECUREFILE_WRONGTYPE	SECUREFILE LOBのみのコールで、BASICFILE LOBが使用されました。

使用上の注意

このプロシージャを起動することは、オフセット位置の既存のバイト数/文字数を削除して、オフセット位置に新しいバイト数/文字数を挿入することと同様です。

---

FREETEMPORARYプロシージャ

このプロシージャは、デフォルト一時表領域内の一時BLOBまたはCLOBを解放します。

構文

DBMS_LOB.FREETEMPORARY (
   lob_loc  IN OUT  NOCOPY BLOB);

DBMS_LOB.FREETEMPORARY (
   lob_loc  IN OUT  NOCOPY CLOB CHARACTER SET ANY_CS);

パラメータ

表69-43 FREETEMPORARYプロシージャのパラメータ

パラメータ	説明
lob_loc	LOBロケータ。詳細は、「使用上の注意」を参照してください。

使用上の注意

• 新しい一時LOBの作成時に、同じ継続時間（セッション、トランザクション、コール）で使用されている一時LOBが存在しない場合は、新しい一時LOBセグメントが作成されます。一時LOBを解放すると、その一時LOBによって消費されていた領域が一時セグメントに解放されます。同じ継続時間が指定されているその他の一時LOBが存在しない場合は、一時セグメントも解放されます。

• FREETEMPORARYへのコール後、解放されたLOBロケータには無効のマークが設定されます。

• 無効のLOBロケータが、OCIのOCILobLocatorAssignを使用して、またはPL/SQLの割当て操作によって別のLOBロケータに割り当てられている場合、割当て先も解放され、無効のマークが設定されます。

関連項目: このプロシージャの使用方法の詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください。

---

GET_STORAGE_LIMITファンクション

このファンクションは、指定したLOBのLOB記憶域制限を戻します。

構文

DBMS_LOB.GET_STORAGE_LIMIT (
   lob_loc  IN CLOB CHARACTER SET ANY_CS)
 RETURN INTEGER;

DBMS_LOB.GET_STORAGE_LIMIT (
   lob_loc  IN BLOB)
 RETURN INTEGER;

プラグマ

PRAGMA RESTRICT_REFERENCES(get_storage_limit, WNDS, RNDS, WNPS, RNPS);

パラメータ

表69-44 GET_STORAGE_LIMITファンクションのパラメータ

パラメータ	説明
lob_loc	LOBロケータ。詳細は、「使用上の注意」を参照してください。

戻り値

このファンクションから戻される値は、指定したLOBロケータの最大許容サイズです。 BLOBの場合、戻り値は、LOBが存在する表領域のブロック・サイズによって異なり、表領域のブロック・サイズの（2³²）-1（4294967295）倍として計算されます。 CLOB/NCLOBの場合、戻り値は、表領域のブロック・サイズの（2³²）-1（4294967295）倍をCLOB/NCLOBの文字幅で割った値になります。

使用上の注意

関連項目: LOB記憶域制限の詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください。

---

GETCHUNKSIZEファンクション

表の作成時に、チャンク・ファクタ（表領域ブロックのバイト単位の倍数）を指定できます。これは、LOB値のアクセスまたは変更時にLOBデータ・レイヤーによって使用されるチャンク・サイズに対応します。チャンクの一部はシステム関連情報の格納に使用され、それ以外の部分にLOB値が格納されます。

このファンクションは、LOB値を格納するLOBチャンクで使用される領域容量を戻します。

構文

DBMS_LOB.GETCHUNKSIZE (
   lob_loc IN BLOB)
  RETURN INTEGER;

DBMS_LOB.GETCHUNKSIZE (
   lob_loc IN CLOB CHARACTER SET ANY_CS)
  RETURN INTEGER;

プラグマ

PRAGMA RESTRICT_REFERENCES(getchunksize, WNDS, RNDS, WNPS, RNPS);

パラメータ

表69-45 GETCHUNKSIZEファンクションのパラメータ

パラメータ	説明
lob_loc	LOBロケータ。詳細は、「使用上の注意」を参照してください。

戻り値

BLOBの場合に戻される値はバイト単位です。CLOBの場合に戻される値は文字単位です。

使用上の注意

基本的なLOBファイルの場合、このチャンク・サイズの倍数を使用して読取り/書込み要求を入力すると、パフォーマンスが向上します。LOBチャンクはバージョン化されるため、書込みの場合にはさらに利点があります。すべての書込みがチャンクを基準に行われると、余分なバージョン分割が行われず、重複もしません。同じチャンクに対してWRITEコールを複数回発行するかわりに、1つのチャンクのサイズ内でWRITEコールを十分な数だけまとめることができます。

これらのパフォーマンスを向上させる方法は、SecureFilesには適用されません。

関連項目: このプロシージャの使用方法の詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください。

例外

表69-46 GETCHUNKSIZEプロシージャの例外

例外	説明
BUFFERING_ENABLED	LOBでバッファが有効になっている場合、LOBバッファを有効にした状態では操作を実行できません。

---

GETLENGTHファンクション

このファンクションは、指定されたLOB値の長さを取得します。長さは、バイト数または文字数で戻されます。

BFILEの場合に戻される長さには、EOF（存在している場合）が含まれます。以前に行ったERASEまたはWRITE操作でLOBに挿入された0（ゼロ）バイトまたは空白のFILLERも長さに含まれます。空の内部LOBの長さは0（ゼロ）です。

構文

DBMS_LOB.GETLENGTH (
   lob_loc    IN  BLOB)
  RETURN INTEGER;

DBMS_LOB.GETLENGTH (
   lob_loc    IN  CLOB   CHARACTER SET ANY_CS)
  RETURN INTEGER;

DBMS_LOB.GETLENGTH (
   file_loc    IN  BFILE)
  RETURN INTEGER;

プラグマ

pragma restrict_references(GETLENGTH, WNDS, WNPS, RNDS, RNPS);

パラメータ

表69-47 GETLENGTHファンクションのパラメータ

パラメータ	説明
file_loc	長さが戻されるLOBのファイル・ロケータ

戻り値

LOBの長さが、INTEGERとしてバイト数または文字数で戻されます。 入力LOBがNULLの場合または入力lob_locがNULLの場合は、NULLが戻されます。BFILEの場合は、次の場合にエラーが戻されます。

• lob_locに必要なディレクトリ権限とオペレーティング・システム権限がない場合

• オペレーティング・システム読込みエラーのために、lob_locを読み込むことができない場合

  
  

  関連項目: このプロシージャの使用方法の詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください。

  
  

例外

表69-48 GETLENGHTHプロシージャの例外

例外	説明
BUFFERING_ENABLED	LOBでバッファが有効になっている場合、LOBバッファを有効にした状態では操作を実行できません。

---

GETOPTIONSファンクション

このファンクションは、特定のLOBのoption_typeフィールドに対応する設定を取得します。

構文

DBMS_LOB.GETOPTIONS (
   lob_loc             IN     BLOB,
   option_types        IN     PLS_INTEGER)
 RETURN PLS_INTEGER;

DBMS_LOB.GETOPTIONS (
  lob_loc             IN     CLOB HARACTER SET ANY_CS,
  option_types        IN     PLS_INTEGER)
RETURN PLS_INTEGER;

パラメータ

表69-49 GETOPTIONSファンクションのパラメータ

パラメータ	説明
lob_loc	検査するLOBのロケータ。詳細は、「使用上の注意」を参照してください。
option_type	「DBMS_LOBのオプション・タイプ」を参照してください。

戻り値

戻り値は、渡されるオプション・タイプ（「DBMS_LOBのオプション・タイプ」を参照）に応じて、COMPRESS_ON、ENCRYPT_ONおよびDEDUPLICATE_ON（「DBMS_LOBのオプション値」を参照）の組合せになります。

例外

表69-50 GETOPTIONSファンクションの例外

例外	説明
SECUREFILE_BADLOB	操作に対してサポートされていないオブジェクト・タイプ。
INVALID_ARGVAL	パラメータ値が無効でした。
QUERY_WRITE	問合せ時に操作を実行できません。
BUFFERING_ENABLED	LOBバッファを有効にした状態では操作を実行できません。
SECUREFILE_BADLOB	SECUREFILE LOBのみのコールで、SECUREFILE以外のLOBが使用されました。
SECUREFILE_WRONGTYPE	SECUREFILE LOBのみのコールで、BASICFILE LOBが使用されました。

---

INSTRファンクション

このファンクションは、指定されたオフセットを開始位置として、LOBにおけるパターンのn番目に一致した位置を戻します。

構文

DBMS_LOB.INSTR (
   lob_loc    IN   BLOB,
   pattern    IN   RAW,
   offset     IN   INTEGER := 1,
   nth        IN   INTEGER := 1)
  RETURN INTEGER;

DBMS_LOB.INSTR (
   lob_loc    IN   CLOB      CHARACTER SET ANY_CS,
   pattern    IN   VARCHAR2  CHARACTER SET lob_loc%CHARSET,
   offset     IN   INTEGER := 1,
   nth        IN   INTEGER := 1)
  RETURN INTEGER;

DBMS_LOB.INSTR (
   file_loc   IN   BFILE,
   pattern    IN   RAW,
   offset     IN   INTEGER := 1,
   nth        IN   INTEGER := 1)
  RETURN INTEGER;

プラグマ

pragma restrict_references(INSTR, WNDS, WNPS, RNDS, RNPS);

パラメータ

表69-51 INSTRファンクションのパラメータ

パラメータ	説明
lob_loc	検査するLOBのロケータ。詳細は、「使用上の注意」を参照してください。
file_loc	検査するLOBのファイル・ロケータ。
pattern	テスト対象のパターン。パターンは、BLOBの場合はRAWバイトのグループ、CLOBの場合は文字列（VARCHAR2）です。パターンの最大サイズは16383バイトです。
offset	パターン・マッチングの開始位置を示す絶対オフセット（起点: 1）。BLOBの場合はバイト数、CLOBの場合は文字数で指定します。
nth	出現番号。1から始まります。

戻り値

表69-52 INSTRファンクションの戻り値

戻り値	説明
INTEGER	一致したパターンの先頭のオフセット。バイト数または文字数で示されます。 パターンが見つからない場合は0（ゼロ）が戻されます。
NULL	次のいずれかです。 - INパラメータのいずれか1つ以上がNULLまたはINVALIDの場合 -offset < 1またはoffset > LOBMAXSIZE - nth < 1 -nth > LOBMAXSIZE

使用上の注意

VARCHAR2バッファ（patternパラメータ）の形式は、CLOBパラメータの形式と一致する必要があります。つまり、入力LOBのパラメータの型がNCLOBの場合、バッファにはNCHARデータが含まれる必要があります。これに対して、入力LOBのパラメータの型がCLOBの場合、バッファにはCHARデータが含まれる必要があります。

BFILEの場合は、この操作を行う前に、FILEOPEN操作でファイルをあらかじめオープンしておく必要があります。

INSTRなど、パターン・マッチング用にRAWまたはVARCHAR2パラメータを受け入れる操作では、パターン・パラメータまたは副文字列において、正規表現または特殊一致文字（例: SQLのLIKE）はサポートされていません。

例外

表69-53 BFILEに関するINSTRファンクションの例外

例外	説明
UNOPENED_FILE	ファイルが入力ロケータを使用してオープンされていません。
NOEXIST_DIRECTORY	ディレクトリが存在しません。
NOPRIV_DIRECTORY	ディレクトリに対する権限がありません。
INVALID_DIRECTORY	ディレクトリがファイルのオープン後に無効となりました。
INVALID_OPERATION	ファイルが存在しないか、またはファイルのアクセス権限がありません。
BUFFERING_ENABLED	LOBでバッファが有効になっている場合、LOBバッファを有効にした状態では操作を実行できません。

関連項目: 「SUBSTRファンクション」 このプロシージャの使用方法の詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください。

---

ISOPENファンクション

このファンクションは、LOBが入力ロケータを使用してすでにオープンされているかどうかをチェックします。このサブプログラムは、内部および外部LOB用です。

構文

DBMS_LOB.ISOPEN (
   lob_loc IN BLOB)
  RETURN INTEGER;

DBMS_LOB.ISOPEN (
   lob_loc IN CLOB CHARACTER SET ANY_CS)
  RETURN INTEGER;

DBMS_LOB.ISOPEN (
   file_loc IN BFILE)
  RETURN INTEGER;

プラグマ

PRAGMA RESTRICT_REFERENCES(isopen, WNDS, RNDS, WNPS, RNPS);

パラメータ

表69-54 ISOPENファンクションのパラメータ

パラメータ	説明
lob_loc	LOBロケータ。詳細は、「使用上の注意」を参照してください。
file_loc	ファイル・ロケータ。

戻り値

戻り値は、LOBがオープンしている場合は1、それ以外の場合は0（ゼロ）です。

使用上の注意

BFILESの場合、オープンされているかどうかはロケータと関連付けられています。入力ロケータがOPENに渡されていない場合、そのBFILEはこのロケータによってオープンされていないとみなされます。ただし、別のロケータがBFILEをオープンしている可能性はあります。異なるロケータを使用すると、同じBFILE上で複数のOPENを実行できます。

内部LOBの場合、オープンされているかどうかは、ロケータではなくそのLOBに関連付けられています。ロケータ1がLOBをオープンした場合、ロケータ2もそのLOBはオープンしているとみなします。内部LOBの場合は、LOBが実際にオープンしているかどうかを調べるにはサーバー上の状態をチェックするため、ISOPENでラウンドトリップが必要です。

外部LOB（BFILE）の場合も、サーバーに状態が保持されているため、ISOPENでラウンドトリップが必要です。

関連項目: このプロシージャの使用方法の詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください。

---

ISTEMPORARYファンクション

このファンクションはLOBインスタンスが一時的であるかどうかを判断します。

構文

DBMS_LOB.ISTEMPORARY (
   lob_loc IN BLOB)
  RETURN INTEGER;

DBMS_LOB.ISTEMPORARY (
   lob_loc IN CLOB CHARACTER SET ANY_CS)
  RETURN INTEGER;

プラグマ

PRAGMA RESTRICT_REFERENCES(istemporary, WNDS, RNDS, WNPS, RNPS);

パラメータ

表69-55 ISTEMPORARYファンクションのパラメータ

パラメータ	説明
lob_loc	LOBロケータ。詳細は、「使用上の注意」を参照してください。

戻り値

戻り値は、LOBが一時的にオープンしている場合は1、それ以外の場合は0（ゼロ）です。

関連項目: このプロシージャの使用方法の詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください。

---

LOADBLOBFROMFILEプロシージャ

このプロシージャは、BFILEのデータを内部BLOBにロードします。結果はLOADFROMFILEと同じで、新しいオフセットを戻します。

構文

DBMS_LOB.LOADBLOBFROMFILE (
   dest_lob    IN OUT NOCOPY BLOB,
   src_bfile   IN            BFILE,
   amount      IN            INTEGER,
   dest_offset IN OUT        INTEGER,
   src_offset  IN OUT        INTEGER);

パラメータ

表69-56 LOADBLOBFROMFILEプロシージャのパラメータ

パラメータ	説明
dest_lob	ロード先のBLOBロケータ。
src_bfile	ロード元のBFILEロケータ。
amount	BFILEからロードするバイト数。 BFILEの終わりまでロードするDBMS_LOB.LOBMAXSIZEを使用することもできます。
dest_offset	(IN）宛先BLOBの書込み開始位置を示すオフセット（起点: 1）。バイト数で指定します。（OUT）この書込み終了直後の宛先BLOBの新規オフセット。バイト数で示されます。次の書込みの開始位置でもあります。
src_offset	（IN）ソースBFILEの読込み開始位置を示すオフセット（起点: 1）。バイト数で指定します。（OUT）この読込み終了直後のソースBFILEのオフセット。バイト数で示されます。次の読込みの開始位置でもあります。

使用上の注意

ソースおよび宛先の両方のLOBに対するオフセット、およびソースBFILEからコピーするバイト数を指定できます。 amountおよびsrc_offsetは、BFILEを参照するためバイト単位です。dest_offsetは、BLOBの場合はバイト単位です。

宛先LOBに指定したオフセットが、現在そのLOBに格納されているデータの終わりを超えている場合は、宛先BLOBに、0（ゼロ）バイトのFILLERまたは空白が挿入されます。オフセットが宛先LOBの現行の長さより小さい場合、既存のデータは上書きされます。

入力amountおよびoffsetを加算した値がBFILE内のデータの長さを超えた場合はエラーが発生します（ただし、指定されているamountが、BFILEの終わりに達するまでロードするように指定できるLOBMAXSIZEの場合を除きます）。

OPEN/CLOSE操作内のLOB操作のラップは必須ではありません。操作を実行する前にLOBをオープンしなかった場合、LOB列のファンクション索引およびドメイン索引は、コール中に更新されます。ただし、操作を実行する前にLOBをオープンした場合は、トランザクションのコミットまたはロールバックを実行する前にクローズする必要があります。内部LOBがクローズされるときに、LOB列のファンクション索引およびドメイン索引が更新されます。

OPEN/CLOSE内のLOB操作をラップしなかった場合、ファンクション索引およびドメイン索引はLOBへ書き込むたびに更新されます。これにより、パフォーマンスに悪影響を及ぼす可能性があります。したがって、LOBへの書込み操作をOPENまたはCLOSE文の中に囲むことをお薦めします。

定数およびデフォルト

パラメータを省略する簡単な方法はありません。IN/OUTパラメータに変数を宣言するか、またはINパラメータにデフォルト値を指定します。使用可能な定数およびデフォルトを次に示します。

表69-57 パラメータのデフォルト値

パラメータ	デフォルト値	説明
amount	DBMS_LOB.LOBMAXSIZE (IN)	ファイル全体をロードします。
dest_offset	1（IN）	先頭から開始します。
src_offset	1（IN）	先頭から開始します。

DBMSLOB.SQLで定義される定数

lobmaxsize                    CONSTANT INTEGER        := DBMS_LOB.LOBMAXSIZE;

例外

表69-58 LOADBLOBFROMFILEプロシージャの例外

例外	説明
VALUE_ERROR	入力パラメータのいずれかがNULLまたはINVALIDです。
INVALID_ARGVAL	次のいずれかです。 - src_offsetまたはdest_offset < 1 - src_offsetまたはdest_offset > LOBMAXSIZE。 - amount < 1 - amount > LOBMAXSIZE
BUFFERING_ENABLED	BLOBでバッファが有効になっている場合、LOBバッファを有効にした状態では操作を実行できません。

関連項目: このプロシージャの使用方法の詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください。

---

LOADCLOBFROMFILEプロシージャ

このプロシージャは、BFILEのデータを必要なキャラクタ・セット変換を行った後、内部CLOB/NCLOBにロードし、新しいオフセットを戻します。

構文

DBMS_LOB.LOADCLOBFROMFILE (
   dest_lob       IN OUT NOCOPY   NOCOPY CLOB CHARACTER SET ANY_CS,
   src_bfile      IN              BFILE,
   amount         IN              INTEGER,
   dest_offset    IN OUT          INTEGER,
   src_offset     IN OUT          INTEGER,
   bfile_csid     IN              NUMBER,
   lang_context   IN OUT          INTEGER,
   warning        OUT             INTEGER);

パラメータ

表69-59 LOADCLOBFROMFILEプロシージャのパラメータ

パラメータ	説明
dest_lob	ロード先のCLOB/NCLOBロケータ。
src_bfile	ロード元のBFILEロケータ。
amount	BFILEからロードするバイト数。 BFILEの終わりまでロードするDBMS_LOB.LOBMAXSIZEを使用することもできます。
dest_offset	（IN）宛先CLOBの書込み開始位置を示すオフセット（起点: 1）。文字数で指定します。 （OUT）このロード終了直後の新規オフセット。文字数で示されます。次のロードの開始位置でもあります。常に、ロード終了後の最初の完全な文字の開始位置を示します。最後の文字が完全でない場合は、部分文字の先頭までオフセットが戻ります。
src_offset	（IN）ソースBFILEの読込み開始位置を示すオフセット（起点: 1）。バイト数で指定します。（OUT）この読込み終了直後のソースBFILEのオフセット。バイト数で示されます。次の読込みの開始位置でもあります。
bfile_csid	ソース（BFILE）ファイルのキャラクタ・セットID。
lang_context	（IN）現在のロードに関する、シフト・ステータスなどの言語コンテキスト。 （OUT）現在のロードが停止した時点の言語コンテキスト。同じソースから継続してロードする場合に、次のロードで使用されます。この情報は、ユーザーがこの情報を使用してソース・データを失ったり、誤って解釈することなく継続してロードできるように戻されます。最初のロードの場合、または特に必要ない場合は、デフォルトの0（ゼロ）を使用してください。この言語コンテキストの詳細は、ユーザーには隠されています。コールするときに、その内容を認識している必要はありません。
warning	（OUT）警告メッセージ。ロード時になんらかの異常が発生したことを示します。ユーザーのミスが原因の場合と、それ以外の場合があります。ロードは要求に応じて完了され、警告メッセージをチェックするかどうかはユーザーが判断します。現在、発生する可能性があるのは、変換不可能な文字に関する警告のみです。これは、ソース内の文字が宛先の文字に正しく変換できない場合に発生します。その位置には、デフォルトの置換文字（例: '?'）が使用されます。 メッセージは、定数値DBMS_LOB.WARN_INCONVERTIBLE_CHARに定義されています。

使用上の注意

ソースおよび宛先の両方のLOBに対するオフセット、およびソースBFILEからコピーするバイト数を指定できます。 amountおよびsrc_offsetは、BFILEを参照するためバイト単位です。dest_offsetは、CLOBの場合は文字単位です。

宛先LOBに指定したオフセットが、現在そのLOBに格納されているデータの終わりを超えている場合は、宛先CLOBに、0（ゼロ）バイトのFILLERまたは空白が挿入されます。オフセットが宛先LOBの現行の長さより小さい場合、既存のデータは上書きされます。

入力amountおよびoffsetを加算した値がBFILE内のデータの長さを超えた場合はエラーが発生します（ただし、指定されているamountが、BFILEの終わりに達するまでロードするように指定できるLOBMAXSIZEの場合を除きます）。

次の要件に注意してください。

• 宛先のキャラクタ・セットは常に、CLOBの場合はデータベース・キャラクタ・セットおよびNCLOBの場合は各国語キャラクタ・セットと同じです。

• csid=0はデフォルトの動作を示します。ソースのcsidのかわりに、CLOBの場合はデータベースcsid、NCLOBの場合は各国語csidを使用します。この場合でも、可変幅の場合は変換が必要です。

• OPEN/CLOSE操作内のLOB操作のラップは必須ではありません。操作を実行する前にLOBをオープンしなかった場合、LOB列のファンクション索引およびドメイン索引は、コール中に更新されます。ただし、操作を実行する前にLOBをオープンした場合は、トランザクションのコミットまたはロールバックを実行する前にクローズする必要があります。内部LOBがクローズされるときに、LOB列のファンクション索引およびドメイン索引が更新されます。

  OPEN/CLOSE内のLOB操作をラップしなかった場合、ファンクション索引およびドメイン索引はLOBへ書き込むたびに更新されます。これにより、パフォーマンスに悪影響を及ぼす可能性があります。したがって、LOBへの書込み操作をOPENまたはCLOSE文の中に囲むことをお薦めします。

ソースBFILEには、Unicodeキャラクタ・セットのデータを含めることができます。Unicode標準では、Unicode文字を一連のバイトにマッピングする複数のコード体系が定義されています。表69-60「サポートされているUnicodeコード体系」に、このサブプログラムでサポートされているUnicodeコード体系を示します。

表69-60 サポートされているUnicodeコード体系

コード体系	Oracle名	bfile_csid値
UTF-8	AL32UTF8	873
UTF-16BE	AL16UTF16	2000
UTF-16LE	AL16UTF16LE	2002
CESU-8	UTF8	871
UTF-EBCDIC	UTFE	872
UTF-16	UTF16	1000

3つすべてのUTF-16コード体系で、Unicode文字は2バイトの符号なし整数としてエンコードされます。整数はビッグ・エンディアンまたはリトル・エンディアンのバイト順で格納できます。UTF-16BEコード体系では、ビッグ・エンディアン・データが定義されます。UTF-16LEコード体系では、リトル・エンディアン・データが定義されます。 UTF-16コード体系では、ソースBFILE内の最初の2バイトに、バイト順序を定義するバイト順序マーク（BOM）文字が格納されている必要があります。BOMコードは0xFEFFです。 このコードが{0xFE,0xFF}として格納されている場合、データはビッグ・エンディアンと解釈されます。 このコードが{0xFF,0xFE}として格納されている場合、データはリトル・エンディアンと解釈されます。

UTF-8およびCESU-8コード体系では、バイト順序マークは{0xEF,0xBB, 0xBF}として格納されます。いずれのUnicodeコード体系でも、ファイルの先頭の対応するBOM順序は、認識されますが、宛先LOBにはロードされません。

定数

使用可能な定数およびデフォルト値を次に示します。

表69-61 パラメータのデフォルト値

パラメータ	デフォルト値	説明
amount	DBMS_LOB.LOBMAXSIZE (IN)	ファイル全体をロードします。
dest_offset	1（IN）	先頭から開始します。
src_offset	1（IN）	先頭から開始します。
csid	0（IN）	デフォルトのcsid。宛先のcsidを使用します。
lang_context	0（IN）	デフォルトの言語コンテキスト。
warning	0（OUT）	警告メッセージはありません。問題ありません。

DBMSLOB.SQLで定義される定数

lobmaxsize                    CONSTANT INTEGER        := 18446744073709551615;
warn_inconvertible_char       CONSTANT INTEGER        := 1;
default_csid                  CONSTANT INTEGER        := 0;
default_lang_ctx              CONSTANT INTEGER        := 0;
no_warning                    CONSTANT INTEGER        := 0;

例外

表69-62 LOADCLOBFROMFILEプロシージャの例外

例外	説明
VALUE_ERROR	入力パラメータのいずれかがNULLまたはINVALIDです。
INVALID_ARGVAL	次のいずれかです。 - src_offsetまたはdest_offset < 1 - src_offsetまたはdest_offset > LOBMAXSIZE。 - amount < 1 - amount > LOBMAXSIZE
BUFFERING_ENABLED	CLOBでバッファが有効になっている場合、LOBバッファを有効にした状態では操作を実行できません。

関連項目: このプロシージャの使用方法の詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください。

---

LOADFROMFILEプロシージャ

このプロシージャは、ソース外部LOB（BFILE）の全体または一部を宛先内部LOBにコピーします。

構文

DBMS_LOB.LOADFROMFILE (
   dest_lob    IN OUT NOCOPY BLOB,
   src_file    IN            BFILE,
   amount      IN            INTEGER,
   dest_offset IN            INTEGER  := 1,
   src_offset  IN            INTEGER  := 1);

パラメータ

表69-63 LOADFROMFILEプロシージャのパラメータ

パラメータ	説明
dest_lob	ロード先のLOBロケータ。
src_file	ロード元のBFILEロケータ。
amount	BFILEからロードするバイト数。
dest_offset	宛先LOBのロード開始位置を示すオフセット（起点: 1）。バイト数または文字数で指定します。
src_offset	ソースBFILEのロード開始位置を示すオフセット（起点: 1）。バイト数で指定します。

使用上の注意

ソースおよび宛先の両方のLOBに対するオフセット、およびソースBFILEからコピーするバイト数を指定できます。 amountおよびsrc_offsetは、BFILEを参照するためバイト単位です。dest_offsetは、BLOBの場合はバイト単位、CLOBの場合は文字単位です。

注意: 入力BFILEは、このプロシージャを使用する前にオープンしている必要があります。バイナリBFILEデータがCLOBにロードされる場合、キャラクタ・セット変換は暗黙的には実行されません。BFILEデータは、データベース内のCLOBと同じキャラクタ・セットであることが必要です。これを検証するためのエラー・チェックは実行されません。

宛先LOBに指定したオフセットが、現在そのLOBに格納されているデータの終わりを超えている場合は、宛先BLOBまたはCLOBに、0（ゼロ）バイトのFILLERまたは空白がそれぞれ挿入されます。オフセットが宛先LOBの現行の長さより小さい場合、既存のデータは上書きされます。

入力amountおよびoffsetを加算した値がBFILE内のデータの長さを超えた場合はエラーが発生します。

注意: UTF-8のようにキャラクタ・セットの幅が変化する場合、LOB値は固定幅形式のUCS2で格納されます。 したがって、DBMS_LOB.LOADFROMFILEを使用している場合、BFILEのデータはUTF-8キャラクタ・セットではなくUCS2キャラクタ・セットにする必要があります。 ただし、CLOBまたはNCLOBにデータをロードするには、LOADFROMFILEではなくsql*loaderを使用してください。sql*loaderは、必要なキャラクタ・セット変換を提供します。

オープン/クローズ・インタフェース内のLOB操作のラップは必須ではありません。操作を実行する前にLOBをオープンしなかった場合、LOB列のファンクション索引およびドメイン索引は、コール中に更新されます。ただし、操作を実行する前にLOBをオープンした場合は、トランザクションのコミットまたはロールバックを実行する前にクローズする必要があります。内部LOBがクローズされるときに、LOB列のファンクション索引およびドメイン索引が更新されます。

オープン/クローズAPI内のLOB操作をラップしなかった場合、ファンクション索引およびドメイン索引はLOBへ書き込むたびに更新されます。これにより、パフォーマンスに悪影響を及ぼす可能性があります。したがって、LOBへの書込み操作をOPENまたはCLOSE文の中に囲むことをお薦めします。

例外

表69-64 LOADFROMFILEプロシージャの例外

例外	説明
VALUE_ERROR	入力パラメータのいずれかがNULLまたはINVALIDです。
INVALID_ARGVAL	次のいずれかです。 - src_offsetまたはdest_offset < 1 - src_offsetまたはdest_offset > LOBMAXSIZE。 - amount < 1 - amount > LOBMAXSIZE

関連項目: このプロシージャの使用方法の詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください。

---

OPENプロシージャ

このプロシージャは、指定されたモードで、（内部または外部）LOBをオープンします。有効なモードは読取り専用と読取り/書込みです。

構文

DBMS_LOB.OPEN (
   lob_loc   IN OUT NOCOPY BLOB,
   open_mode IN            BINARY_INTEGER);

DBMS_LOB.OPEN (
   lob_loc   IN OUT NOCOPY CLOB CHARACTER SET ANY_CS,
   open_mode IN            BINARY_INTEGER);

DBMS_LOB.OPEN (
   file_loc  IN OUT NOCOPY BFILE,
   open_mode IN            BINARY_INTEGER := file_readonly);

パラメータ

表69-65 OPENプロシージャのパラメータ

パラメータ	説明
lob_loc	LOBロケータ。詳細は、「使用上の注意」を参照してください。
open_mode	オープンするモード。 BLOBおよびCLOB型の場合、モードはLOB_READONLYまたはLOB_READWRITEのいずれかに指定できます。 BFILE型の場合、モードはFILE_READONLYである必要があります。

使用上の注意

注意: LOBが読取り専用モードでオープンされた場合は、そのLOBに書込みを行おうとすると、エラーが戻されます。BFILEは、読取り専用モードでのみオープンできます。

OPENでは、内部または外部LOBのいずれの場合もサーバーへのラウンドトリップが必要です。内部LOBの場合、OPENはOPENコールに依存しているその他のコードのトリガーとなります。外部LOB（BFILE）の場合は、サーバー側の実際のオペレーティング・システム・ファイルがオープンされるため、ラウンドトリップが必要です。

オープン/クローズ・インタフェース内のすべてのLOB操作のラップは必須ではありません。ただし、LOBをオープンしている場合は、トランザクションのコミットまたはロールバックを実行する前にクローズする必要があります。クローズしない場合は、エラーが発生します。内部LOBがクローズされるときに、LOB列のファンクション索引およびドメイン索引が更新されます。

トランザクションによりオープンされたLOBをすべてクローズする前にトランザクションをコミットした場合、エラーが発生します。エラーが戻された場合、LOBのオープンは廃棄されますが、トランザクションのコミットは正常に行われます。したがって、そのトランザクションにおけるLOBおよび非LOBデータの変更はすべてコミットされますが、ドメイン索引およびファンクションベースの索引は更新されません。このような場合は、LOB列のファンクション索引およびドメイン索引を再構築する必要があります。

関連項目: このプロシージャの使用方法の詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください。

---

READプロシージャ

このプロシージャは、LOBの一部を読み込み、LOBの先頭からの絶対オフセットから開始し、指定された量のデータをbufferパラメータに戻します。

実際に読み込まれたバイト数または文字数は、amountパラメータに戻されます。 入力offsetがLOBの終わりを超えた位置を指している場合、amountは0（ゼロ）に設定され、NO_DATA_FOUND例外が発生します。

構文

DBMS_LOB.READ (
   lob_loc   IN             BLOB,
   amount    IN OUT  NOCOPY INTEGER,
   offset    IN             INTEGER,
   buffer    OUT            RAW);

DBMS_LOB.READ (
   lob_loc   IN             CLOB CHARACTER SET ANY_CS,
   amount    IN OUT  NOCOPY INTEGER,
   offset    IN             INTEGER,
   buffer    OUT            VARCHAR2 CHARACTER SET lob_loc%CHARSET);

DBMS_LOB.READ (
   file_loc   IN             BFILE,
   amount    IN OUT   NOCOPY INTEGER,
   offset    IN              INTEGER,
   buffer    OUT             RAW);

パラメータ

表69-66 READプロシージャのパラメータ

パラメータ	説明
lob_loc	読み込むLOBのロケータ。詳細は、「使用上の注意」を参照してください。
file_loc	検査するLOBのファイル・ロケータ。
amount	読み込む、または読み込まれたバイト数（BLOBの場合）または文字数（CLOBの場合）。
offset	LOBの先頭からのオフセット（起点: 1）。BLOBの場合はバイト数、CLOBの場合は文字数で指定します。
buffer	読取り操作用の出力バッファ。

例外

表69-67に、すべてのLOBインスタンスに該当する例外を示します。表69-68に、BFILEのみに該当する例外を示します。

表69-67 READプロシージャの例外

例外	説明
VALUE_ERROR	lob_loc、amountまたはoffsetパラメータのいずれかがNULLです。
INVALID_ARGVAL	次のいずれかです。 - amount < 1 - amount > MAXBUFSIZE - offset < 1 - offset > LOBMAXSIZE - amount（バイト数または文字数）がbufferの容量を超えています。
NO_DATA_FOUND	LOBの終わりに達し、LOBから読み込むバイトまたは文字がありません。amountの値は0（ゼロ）です。

表69-68 BFILEに関するREADプロシージャの例外

例外	説明
UNOPENED_FILE	ファイルが入力ロケータを使用してオープンされていません。
NOEXIST_DIRECTORY	ディレクトリが存在しません。
NOPRIV_DIRECTORY	ディレクトリに対する権限がありません。
INVALID_DIRECTORY	ディレクトリがファイルのオープン後に無効となりました。
INVALID_OPERATION	ファイルが存在しないか、またはファイルのアクセス権限がありません。
BUFFERING_ENABLED	LOBでバッファが有効になっている場合、LOBバッファを有効にした状態では操作を実行できません。

使用上の注意

VARCHAR2バッファの形式は、CLOBパラメータの形式と一致する必要があります。つまり、入力LOBのパラメータの型がNCLOBの場合、バッファにはNCHARデータが含まれる必要があります。これに対して、入力LOBのパラメータの型がCLOBの場合、バッファにはCHARデータが含まれる必要があります。

クライアントからDBMS_LOB.READをコールすると（SQL*Plus内からのBEGIN/ENDブロックでのコールなど）、戻されるバッファにはクライアントのキャラクタ・セットのデータが含まれます。データベースは、バッファをユーザーに戻す前に、サーバーのキャラクタ・セットからクライアントのキャラクタ・セットにLOB値を変換します。

関連項目: このプロシージャの使用方法の詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください。

---

SETOPTIONSプロシージャ

このプロシージャは、LOB単位でCSCE機能を使用可能/使用禁止にして、デフォルトのLOB列設定より優先させます。

構文

DBMS_LOB.SETOPTIONS (
   lob_loc             IN     BLOB,
   option_types        IN     PLS_INTEGER,
   options             IN     PLS_INTEGER);

DBMS_LOB.SETOPTIONS (
  lob_loc             IN     CLOB CHARACTER SET ANY_CS,
  option_types        IN     PLS_INTEGER,
  options             IN     PLS_INTEGER);

パラメータ

表69-69 SETOPTIONSプロシージャのパラメータ

パラメータ	説明
lob_loc	検査するLOBのロケータ。詳細は、「使用上の注意」を参照してください。
option_type	「DBMS_LOBのオプション・タイプ」を参照してください。
options	「DBMS_LOBのオプション値」を参照してください。

例外

表69-70 SETOPTIONSプロシージャの例外

例外	説明
SECUREFILE_BADLOB	操作に対してサポートされていないオブジェクト・タイプ。
INVALID_ARGVAL	パラメータ値が無効でした。
QUERY_WRITE	問合せ時に操作を実行できません。
BUFFERING_ENABLED	LOBバッファを有効にした状態では操作を実行できません。
SECUREFILE_WRONGTYPE	SECUREFILE LOBのみのコールで、BASICFILE LOBが使用されました。

使用上の注意

DBMS_LOB.SETOPTIONSを使用して、個々のLOBに対する暗号化を使用可能または使用禁止にすることはできません。

---

SUBSTRファンクション

このファンクションは、LOBの先頭からの絶対offsetから開始し、LOBのamountバイトまたは文字を戻します。

固定幅のnバイトのCLOBの場合、SUBSTRに対する入力amountが（32767/n）を超えると、長さ（32767/n）の文字バッファまたはCLOBの長さのうち、いずれか小さい方が戻されます。可変幅キャラクタ・セットのCLOBの場合、nはCLOBの文字に使用される最大バイト幅です。

構文

DBMS_LOB.SUBSTR (
   lob_loc     IN    BLOB,
   amount      IN    INTEGER := 32767,
   offset      IN    INTEGER := 1)
  RETURN RAW;

DBMS_LOB.SUBSTR (
   lob_loc     IN    CLOB   CHARACTER SET ANY_CS,
   amount      IN    INTEGER := 32767,
   offset      IN    INTEGER := 1)
  RETURN VARCHAR2 CHARACTER SET lob_loc%CHARSET;

DBMS_LOB.SUBSTR (
   file_loc     IN    BFILE,
   amount      IN    INTEGER := 32767,
   offset      IN    INTEGER := 1)
  RETURN RAW;

プラグマ

pragma restrict_references(SUBSTR, WNDS, WNPS, RNDS, RNPS);

パラメータ

表69-71 SUBSTRファンクションのパラメータ

パラメータ	説明
lob_loc	読み込むLOBのロケータ。詳細は、「使用上の注意」を参照してください。
file_loc	検査するLOBのファイル・ロケータ。
amount	読み込むバイト数（BLOBの場合）または文字数（CLOBの場合）。
offset	LOBの先頭からのオフセット（起点: 1）。BLOBの場合はバイト数、CLOBの場合は文字数で指定します。

戻り値

表69-72 SUBSTRファンクションの戻り値

戻り値	説明
RAW	ファンクション・オーバーロード。パラメータにBLOBまたはBFILEを使用します。
VARCHAR2	CLOBのバージョン。
NULL	次のいずれかです。 - 入力パラメータのいずれかがNULLです。 - amount < 1 - amount > 32767 - offset < 1 - offset > LOBMAXSIZE

例外

表69-73 BFILE操作に関するSUBSTRファンクションの例外

例外	説明
UNOPENED_FILE	ファイルが入力ロケータを使用してオープンされていません。
NOEXIST_DIRECTORY	ディレクトリが存在しません。
NOPRIV_DIRECTORY	ディレクトリに対する権限がありません。
INVALID_DIRECTORY	ディレクトリがファイルのオープン後に無効となりました。
INVALID_OPERATION	ファイルが存在しないか、またはファイルのアクセス権限がありません。
BUFFERING_ENABLED	LOBでバッファが有効になっている場合、LOBバッファを有効にした状態では操作を実行できません。

使用上の注意

VARCHAR2バッファの形式は、CLOBパラメータの形式と一致する必要があります。つまり、入力LOBのパラメータの型がNCLOBの場合、バッファにはNCHARデータが含まれる必要があります。これに対して、入力LOBのパラメータの型がCLOBの場合、バッファにはCHARデータが含まれる必要があります。

クライアントからDBMS_LOB.SUBSTRをコールすると（SQL*Plus内からのBEGIN/ENDブロックでのコールなど）、戻されるバッファにはクライアントのキャラクタ・セットのデータが含まれます。データベースは、バッファをユーザーに戻す前に、サーバーのキャラクタ・セットからクライアントのキャラクタ・セットにLOB値を変換します。

関連項目: 「INSTRファンクション」 「READプロシージャ」 このプロシージャの使用方法の詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください。

---

TRIMプロシージャ

このプロシージャは、内部LOBの値をnewlenパラメータで指定された長さに切り捨てます。BLOBの場合はバイト数、CLOBの場合は文字数で長さを指定します。

注意: TRIMプロシージャは、LOBの長さをnewlenパラメータで指定された値に減らします。

空のLOBに対してTRIMを実行すると、何も処理は行われずエラーは戻されません。newlenで指定した新しい長さがLOBのサイズよりも大きい場合は、例外が発生します。

構文

DBMS_LOB.TRIM (
   lob_loc        IN OUT  NOCOPY BLOB,
   newlen         IN             INTEGER);

DBMS_LOB.TRIM (
   lob_loc        IN OUT  NOCOPY CLOB CHARACTER SET ANY_CS,
   newlen         IN             INTEGER);

パラメータ

表69-74 TRIMプロシージャのパラメータ

パラメータ	説明
lob_loc	長さを切り捨てる内部LOBのロケータ。詳細は、「使用上の注意」を参照してください。
newlen	切り捨て後の新しいLOB値の長さ。BLOBの場合はバイト数、CLOBの場合は文字数で指定します。

例外

表69-75 TRIMプロシージャの例外

例外	説明
VALUE_ERROR	lob_locがNULLです。
INVALID_ARGVAL	次のいずれかです。 - new_len < 0 - new_len > LOBMAXSIZE
QUERY_WRITE	問合せまたはPDMLスレーブ内でLOB書込みを実行できません。
BUFFERING_ENABLED	LOBでバッファが有効になっている場合、LOBバッファを有効にした状態では操作を実行できません。

使用上の注意

オープン/クローズ・インタフェース内のLOB操作のラップは必須ではありません。操作を実行する前にLOBをオープンしなかった場合、LOB列のファンクション索引およびドメイン索引は、コール中に更新されます。ただし、操作を実行する前にLOBをオープンした場合は、トランザクションのコミットまたはロールバックを実行する前にクローズする必要があります。内部LOBがクローズされるときに、LOB列のファンクション索引およびドメイン索引が更新されます。

オープン/クローズAPI内のLOB操作をラップしなかった場合、ファンクション索引およびドメイン索引はLOBへ書き込むたびに更新されます。これにより、パフォーマンスに悪影響を及ぼす可能性があります。したがって、LOBへの書込み操作をOPENまたはCLOSE文の中に囲むことをお薦めします。

関連項目: 「ERASEプロシージャ」 「WRITEAPPENDプロシージャ」 このプロシージャの使用方法の詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください。

---

WRITEプロシージャ

このプロシージャは、LOBの先頭からの絶対オフセットから開始し、指定された量のデータを内部LOBに書き込みます。データは、bufferパラメータから書き込まれます。

WRITEは、オフセット位置以降LOBにすでに存在しているデータを、指定した長さだけ置換（上書き）します。

構文

DBMS_LOB.WRITE (
   lob_loc  IN OUT NOCOPY  BLOB,
   amount   IN             INTEGER,
   offset   IN             INTEGER,
   buffer   IN             RAW);

DBMS_LOB.WRITE (
   lob_loc  IN OUT  NOCOPY CLOB   CHARACTER SET ANY_CS,
   amount   IN             INTEGER,
   offset   IN             INTEGER,
   buffer   IN             VARCHAR2 CHARACTER SET lob_loc%CHARSET);

パラメータ

表69-76 WRITEプロシージャのパラメータ

パラメータ	説明
lob_loc	書込み先の内部LOBのロケータ。詳細は、「使用上の注意」を参照してください。
amount	書き込むバイト数（BLOBの場合）または文字数（CLOBの場合）。
offset	LOBの先頭からの書込み操作のオフセット（起点: 1）。BLOBの場合はバイト数、CLOBの場合は文字数で指定します。
buffer	書込み用の入力バッファ。

例外

表69-77 WRITEプロシージャの例外

例外	説明
VALUE_ERROR	lob_loc、amountまたはoffsetパラメータのいずれかがNULL、範囲外またはINVALIDです。
INVALID_ARGVAL	次のいずれかです。 - amount < 1 - amount > MAXBUFSIZE - offset < 1 - offset > LOBMAXSIZE
QUERY_WRITE	問合せまたはPDMLスレーブ内でLOB書込みを実行できません。
BUFFERING_ENABLED	LOBでバッファが有効になっている場合、LOBバッファを有効にした状態では操作を実行できません。
SECUREFILE_OUTOFBOUNDS	FRAGMENT_*が設定されているLOBの終わりを超えて書込み操作を実行しようとしました。

使用上の注意

入力amountがバッファのデータより多い場合はエラーが発生します。入力amountがバッファのデータより少ない場合は、バッファからその量のバイト数または文字数のみLOBに書き込まれます。指定したオフセットが現在そのLOBに格納されているデータの終わりを超えている場合は、BLOBまたはCLOBに、0（ゼロ）バイトのFILLERまたは空白がそれぞれ挿入されます。

VARCHAR2バッファの形式は、CLOBパラメータの形式と一致する必要があります。つまり、入力LOBのパラメータの型がNCLOBの場合、バッファにはNCHARデータが含まれる必要があります。これに対して、入力LOBのパラメータの型がCLOBの場合、バッファにはCHARデータが含まれる必要があります。

クライアントからDBMS_LOB.WRITEをコールするとき（SQL*Plus内からのBEGIN/ENDブロックでのコールなど）は、バッファにクライアントのキャラクタ・セットのデータが含まれている必要があります。データベースは、バッファ・データをLOBに書き込む前に、クライアント側のキャラクタ・セットをサーバー側のキャラクタ・セットに変換します。

オープン/クローズ・インタフェース内のLOB操作のラップは必須ではありません。操作を実行する前にLOBをオープンしなかった場合、LOB列のファンクション索引およびドメイン索引は、コール中に更新されます。ただし、操作を実行する前にLOBをオープンした場合は、トランザクションのコミットまたはロールバックを実行する前にクローズする必要があります。内部LOBがクローズされるときに、LOB列のファンクション索引およびドメイン索引が更新されます。

オープン/クローズAPI内のLOB操作をラップしなかった場合、ファンクション索引およびドメイン索引はLOBへ書き込むたびに更新されます。これにより、パフォーマンスに悪影響を及ぼす可能性があります。したがって、LOBへの書込み操作をOPENまたはCLOSE文の中に囲むことをお薦めします。

関連項目: 「APPENDプロシージャ」 「COPYプロシージャ」 このプロシージャの使用方法の詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください。

---

WRITEAPPENDプロシージャ

このプロシージャは、指定された量のデータを内部LOBの後ろに書き込みます。データは、bufferパラメータから書き込まれます。

構文

DBMS_LOB.WRITEAPPEND (
   lob_loc IN OUT NOCOPY BLOB,
   amount  IN            INTEGER,
   buffer  IN            RAW);

DBMS_LOB.WRITEAPPEND (
   lob_loc IN OUT NOCOPY CLOB CHARACTER SET ANY_CS,
   amount  IN            INTEGER,
   buffer  IN            VARCHAR2 CHARACTER SET lob_loc%CHARSET);

パラメータ

表69-78 WRITEAPPENDプロシージャのパラメータ

パラメータ	説明
lob_loc	書込み先の内部LOBのロケータ。詳細は、「使用上の注意」を参照してください。
amount	書き込むバイト数（BLOBの場合）または文字数（CLOBの場合）。
buffer	書込み用の入力バッファ。

使用上の注意

入力amountがバッファのデータより多い場合はエラーが発生します。入力amountがバッファのデータより少ない場合は、バッファからその量のバイト数または文字数のみLOBの後ろに書き込まれます。

例外

表69-79 WRITEAPPENDプロシージャの例外

例外	説明
VALUE_ERROR	lob_loc、amountまたはoffsetパラメータのいずれかがNULL、範囲外またはINVALIDです。
INVALID_ARGVAL	次のいずれかです。 - amount < 1 - amount > MAXBUFSIZE
QUERY_WRITE	問合せまたはPDMLスレーブ内でLOB書込みを実行できません。
BUFFERING_ENABLED	LOBでバッファが有効になっている場合、LOBバッファを有効にした状態では操作を実行できません。

使用上の注意

VARCHAR2バッファの形式は、CLOBパラメータの形式と一致する必要があります。つまり、入力LOBのパラメータの型がNCLOBの場合、バッファにはNCHARデータが含まれる必要があります。これに対して、入力LOBのパラメータの型がCLOBの場合、バッファにはCHARデータが含まれる必要があります。

クライアントからDBMS_LOB.WRITEAPPENDをコールするとき（SQL*Plus内からのBEGIN/ENDブロックでのコールなど）は、バッファにクライアントのキャラクタ・セットのデータが含まれている必要があります。データベースは、バッファ・データをLOBに書き込む前に、クライアント側のキャラクタ・セットをサーバー側のキャラクタ・セットに変換します。

オープン/クローズ・インタフェース内のLOB操作のラップは必須ではありません。操作を実行する前にLOBをオープンしなかった場合、LOB列のファンクション索引およびドメイン索引は、コール中に更新されます。ただし、操作を実行する前にLOBをオープンした場合は、トランザクションのコミットまたはロールバックを実行する前にクローズする必要があります。内部LOBがクローズされるときに、LOB列のファンクション索引およびドメイン索引が更新されます。

オープン/クローズAPI内のLOB操作をラップしなかった場合、ファンクション索引およびドメイン索引はLOBへ書き込むたびに更新されます。これにより、パフォーマンスに悪影響を及ぼす可能性があります。したがって、LOBへの書込み操作をOPENまたはCLOSE文の中に囲むことをお薦めします。

関連項目: 「APPENDプロシージャ」 「COPYプロシージャ」 「WRITEプロシージャ」 このプロシージャの使用方法の詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください。