52 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 ...

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

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

---

定数

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

file_readonly CONSTANT BINARY_INTEGER := 0;
lob_readonly  CONSTANT BINARY_INTEGER := 0;
lob_readwrite CONSTANT BINARY_INTEGER := 1;
lobmaxsize    CONSTANT INTEGER        := 18446744073709551615;
call          CONSTANT PLS_INTEGER    := 12;
session       CONSTANT PLS_INTEGER    := 10;

---

データ型

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

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（4GB-1）です。

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

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

     JA16SJISFIXED
     

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

     4294967295/2 = 2147483647 characters.
     

• 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操作で、ユーザーがoffset値に3GB、amount値に2GBを指定すると、READでは((4GB-1)-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例外が発生したと想定します。

  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);
  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の最大サイズはdb_block_size初期化パラメータの値に値4294967295をかけた結果に等しくなります。これによって、最大LOBサイズの範囲は8TBから128TBまでとなります。

最大バッファ・サイズ

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

---

使用上の注意

すべてのDBMS_LOBサブプログラムは、LOBロケータをベースにして動作します。DBMS_LOBサブプログラムを正常に実行するためには、データベース表領域または外部ファイル・システムにすでに存在しているLOBを示す入力ロケータを用意する必要があります。 『Oracle Databaseアプリケーション開発者ガイド-ラージ・オブジェクト』の第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アプリケーション開発者ガイド-ラージ･オブジェクト』の外部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. 入力パラメータのいずれかがNULLの場合、DBMS_LOBのファンクションはすべてNULLを戻します。LOBロケータがNULLで入力されると、DBMS_LOBのすべてのプロシージャで例外が発生します。

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

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

4. 一時LOBは値構文に準拠しています。これは、永続LOBとの一貫性を保ち、LOB用のANSI規格に従うためです。このため、OCILobLocatatorAssignまたはPL/SQLで同じ割当てが実行されるたびに、データベースでは一時LOBのコピーが作成されます。

   各ロケータは、それぞれ独自のLOB値を指します。一時LOBを作成するためにあるロケータが使用され、そのロケータが、OCIのOCILobLOcatorAssignを使用して、またはPL/SQLの割当て操作によって別のLOBロケータに割り当てられた場合、データベースは元の一時LOBのコピーを作成し、2番目のロケータがそのコピーを指すようにします。

   複数のユーザーが同じLOBを変更できるようにするには、同じロケータを使用する必要があります。OCIでは、ロケータへのポインタを使用して、そのポインタが同じロケータを指すように割り当てることによって、比較的簡単にこの処理を実行できます。PL/SQLでは、同様の効果を得るには、同じLOB変数を使用してLOBを更新する必要があります。

   次の例は、コピーが作成される場合、または最低1回サーバーへの特別なラウンドトリップが行われる場合を示しています。

   DECLARE
     a blob;
     b blob;
   BEGIN
     dbms_lob.createtemporary(b, TRUE);
     -- the following assignment results in a deep copy
     a := b;
   END;
   
   

   PL/SQLコンパイラは、OUTまたはIN OUTパラメータにバインドされる実引数のテンポラリ・コピーを作成します。実パラメータが一時LOBの場合、テンポラリ・コピーはディープ（値）コピーです。

   次のPL/SQLブロックは、一時LOBをIN OUTパラメータとして渡すことによって、ディープ・コピーが行われる例を示しています。

   DECLARE
     a blob;
     procedure foo(parm IN OUT blob) is
     BEGIN
      ...
     END;
   BEGIN
     dbms_lob.createtemporary(a, TRUE);
     -- the following call results in a deep copy of the blob a
     foo(a);
   END;
   
   

   PL/SQLパラメータの受渡しのためのディープ・コピーを最小限にするためには、可能であればNOCOPYのコンパイラ・ヒントを使用します。

   dbms_lob.createtemporary()に渡される継続期間パラメータがヒントです。新しい一時LOBの継続期間は、PL/SQLのロケータ変数の継続期間と同じです。たとえば、前述のプログラム・ブロックでは、プログラム変数aには常駐フレームの継続期間が設定されます。したがって、ブロックの終わりでは、ファンクションの終了時にaのメモリーが解放されます。

   PL/SQLパッケージ変数を使用して一時LOBが作成された場合、SESSIONの継続期間を持つパッケージ変数の継続期間が設定されます。

   BEGIN
      y clob;
     END;
   /
   BEGIN
      dbms_lob.createtemporary(package.y, TRUE);
   END;
   

---

例外

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

パラメータ

例外

使用上の注意

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

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

---

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

パラメータ

例外

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

使用上の注意

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

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

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

---

COMPAREファンクション

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

構文

DBMS_LOB.COMPARE (
   lob_1            IN BLOB,
   lob_2            IN BLOB,
   amount           IN INTEGER := 4294967295,
   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 := 4294967295,
   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);

パラメータ

戻り値

• 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の指定が（4294967295/n）を超えると、（4294967295/n）またはMax（length(clob1), length(clob2)）のサイズのうち、小さい方の範囲で文字を比較します。

例外

---

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

パラメータ

使用上の注意

事前条件

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

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

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

定数およびデフォルト

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

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

一般的な注意

blob_csidパラメータに宛先LOBの目的のキャラクタ・セットを指定する必要があります。blob_csidには0の値を渡せます。 0の値を渡すと、データベースは目的のキャラクタ・セットがソースLOBのキャラクタ・セットと同じであるとみなしてデータのバイナリ・コピーを実行し、キャラクタ・セットの変換は行いません。

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

例外

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

---

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

パラメータ

使用上の注意

事前条件

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

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

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

定数およびデフォルト

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

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

一般的な注意

blob_csidパラメータに宛先LOBの目的のキャラクタ・セットを指定する必要があります。blob_csidには0の値を渡せます。0の値を渡すと、データベースは、BLOBが宛先CLOBと同じキャラクタ・セットで文字データを格納しているものとみなし、宛先LOBへのデータのバイナリ・コピーを実行して、キャラクタ・セットの変換は行いません。

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

例外

---

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

パラメータ

例外

使用上の注意

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

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

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

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

---

CREATETEMPORARYプロシージャ

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

構文

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

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

パラメータ

---

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

パラメータ

使用上の注意

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

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

例外

使用上の注意

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

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

---

FILECLOSEプロシージャ

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

構文

DBMS_LOB.FILECLOSE (
    file_loc IN OUT NOCOPY BFILE);

パラメータ

例外

---

FILECLOSEALLプロシージャ

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

構文

DBMS_LOB.FILECLOSEALL;

例外

---

FILEEXISTSファンクション

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

構文

DBMS_LOB.FILEEXISTS (
   file_loc     IN    BFILE)
  RETURN INTEGER;

プラグマ

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

パラメータ

戻り値

例外

---

FILEGETNAMEプロシージャ

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

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

構文

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

パラメータ

例外

---

FILEISOPENファンクション

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

構文

DBMS_LOB.FILEISOPEN (
   file_loc   IN    BFILE)
  RETURN INTEGER;

プラグマ

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

パラメータ

戻り値

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

使用上の注意

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

例外

---

FILEOPENプロシージャ

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

構文

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

パラメータ

例外

---

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

パラメータ

使用上の注意

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

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

---

GET_STORAGE_LIMIT

DBMS_LOB.GET_STORAGE_LIMITファンクションは、データベース構成のLOBの記憶域制限を返します。DBMS_LOBパッケージは、この記憶域制限のサイズまでのLOBインスタンスをサポートします。

構文

DBMS_LOB.GET_STORAGE_LIMIT
  RETURN INTEGER;

戻り値

このファンクションから戻される値は、データベース構成のLOBインスタンスの最大許容サイズです。戻り値は、DB_BLOCK_SIZE初期化パラメータの設定によって異なり、DB_BLOCK_SIZE初期化パラメータの値の（4GB-1）倍として計算されます。

使用上の注意

CLOBおよびNCLOBインスタンスは文字数でサイズ計算されますが、BLOBインスタンスはバイト数で計算されることに注意してください。

---

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

パラメータ

戻り値

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

使用上の注意

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

---

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

パラメータ

戻り値

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

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

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

  
  

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

  
  

---

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

パラメータ

戻り値

使用上の注意

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

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

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

例外

---

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

パラメータ

使用上の注意

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

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

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

---

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

パラメータ

戻り値

ロケータが一時LOBを指している場合は、temporaryにTRUEが戻されます。そうでない場合はFALSEが戻されます。

---

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

パラメータ

使用上の注意

ソースおよび宛先の両方の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パラメータにデフォルト値を指定します。使用可能な定数およびデフォルトを次に示します。

DBMSLOB.SQLで定義される定数

lobmaxsize                    CONSTANT INTEGER        := 4294967295;

例外

---

LOADCLOBFROMFILEプロシージャ

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

構文

DBMS_LOB.LOADCLOBFROMFILE (
   dest_lob       IN OUT NOCOPY   BLOB,
   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);

パラメータ

使用上の注意

ソースおよび宛先の両方の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文の中に囲むことをお薦めします。

定数

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

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;

例外

---

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

パラメータ

使用上の注意

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

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

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

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

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

例外

---

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

パラメータ

使用上の注意

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

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

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

---

READプロシージャ

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

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

構文

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

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

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

パラメータ

例外

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

使用上の注意

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

クライアントからDBMS_LOB.READをコールすると（例: SQL*Plus内からのBEGIN/ENDブロックでのコール）、戻されるバッファにはクライアントのキャラクタ・セットのデータが含まれます。データベースは、バッファをユーザーに戻す前に、サーバーのキャラクタ・セットからクライアントのキャラクタ・セットに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);

パラメータ

戻り値

例外

使用上の注意

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

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

---

TRIMプロシージャ

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

空の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);

パラメータ

例外

使用上の注意

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

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

---

WRITEプロシージャ

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

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

構文

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

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

パラメータ

例外

使用上の注意

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

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

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

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

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

---

WRITEAPPENDプロシージャ

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

構文

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

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

パラメータ

使用上の注意

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

例外

使用上の注意

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

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

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

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