88 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パッケージでは、次の表に示す定数が使用されます。

• 表88-1「DBMS_LOBの定数: 基本」

• 表88-2「DBMS_LOBの定数: オプション・タイプ」

• 表88-3「DBMS_LOBの定数: オプション値」

• 表88-4「DBMS_LOBの定数: DBFS状態値のタイプ」

• 表88-5「DBMS_LOBの定数: DBFSキャッシュ・フラグ」

• 表88-6「DBMS_LOBの定数: その他」

表88-1 DBMS_LOBの定数: 基本

定数	タイプ	値	説明
CALL	PLS_INTEGER	12	コール継続時間を含むTEMP LOBを作成します。
FILE_READONLY	BINARY_INTEGER	0	指定したBFILEを読取り専用モードでオープンします。
LOB_READONLY	BINARY_INTEGER	0	指定したLOBを読取り専用モードでオープンします。
LOB_READWRITE	BINARY_INTEGER	1	指定したLOBを読取り/書取りモードでオープンします。
LOBMAXSIZE	INTEGER	18446744073709551615	LOBの最大サイズ(バイト単位)。
SESSION	PLS_INTEGER	10	セッション継続時間を含むTEMP LOBを作成します。

表88-2 DBMS_LOBの定数: オプション・タイプ

定数	定義	値	説明
OPT_COMPRESS	BINARY_INTEGER	1	SECUREFILEの圧縮オプション値を設定/取得します。
OPT_DEDUPLICATE	BINARY_INTEGER	4	SECUREFILEの重複除外オプション値を設定/取得します。
OPT_ENCRYPT	BINARY_INTEGER	2	SECUREFILEの暗号化オプション値を取得します。

表88-3 DBMS_LOBの定数: オプション値

定数	定義	値	説明
COMPRESS_OFF	BINARY_INTEGER	0	SETOPTIONSプロシージャに対しては、圧縮をオフに設定します。GETOPTIONSファンクションに対しては、圧縮はオフになっています。
COMPRESS_ON	BINARY_INTEGER	1	SETOPTIONSプロシージャに対しては、圧縮をオンに設定します。GETOPTIONSファンクションに対しては、圧縮はオンになっています。
DEDUPLICATE_OFF	BINARY_INTEGER	0	SETOPTIONSプロシージャに対しては、重複除外をオフに設定します。GETOPTIONSファンクションに対しては、重複除外はオフになっています。
DEDUPLICATE_ON	BINARY_INTEGER	4	SETOPTIONSプロシージャに対しては、重複除外をオンに設定します。GETOPTIONSファンクションに対しては、重複除外はオンになっています。
ENCRYPT_OFF	BINARY_INTEGER	0	GETOPTIONSファンクションに対しては、暗号化はオフになっています。
ENCRYPT_ON	BINARY_INTEGER	2	GETOPTIONSファンクションに対しては、暗号化はオンになっています。

表88-4 DBMS_LOBの定数: DBFS状態値のタイプ

定数	定義	値	説明
DBFS_LINK_NEVER	PLS_INTEGER	0	LOBはアーカイブされていません。
DBFS_LINK_NO	PLS_INTEGER	2	LOBはアーカイブされていますが、RDBMSに読み込まれています。
DBFS_LINK_YES	PLS_INTEGER	1	LOBは現在アーカイブされています。

表88-5 DBMS_LOBの定数: DBFSキャッシュ・フラグ

定数	定義	値	説明
DBFS_LINK_CACHE	PLS_INTEGER	1	LOBデータをアーカイブに書き込みますが、RDBMS内のデータはキャッシュされたバージョンとして保持します。
DBFS_LINK_NOCACHE	PLS_INTEGER	0	LOBデータをアーカイブに書き込み、RDBMSから削除します。

表88-6 DBMS_LOBの定数: その他

定数	定義	値	説明
CONTENTTYPE_MAX_SIZE	PLS_INTEGER	128	コンテンツ・タイプ文字列に使用できる最大バイト数
DBFS_LINK_PATH_MAX_SIZE	PLS_INTEGER	1024	DBFSパス名の最大長

データ・タイプ

DBMS_LOBパッケージでは、表88-7に示すデータ・タイプが使用されます。

表88-7 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ロケータ変数を入力として受け入れることができます。

使用上の注意

すべての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の新しいコピーをポイントするようになります。変更が行われたロケータと同様、他のロケータもそれ以降同じデータを参照しなくなります。このような状況では、CRスナップショットおよびバージョン・ページによって、ユーザーは独自のバージョンのLOBを簡単に参照できるため、永続LOBではディープ・コピーは生成されません。

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

一時LOBは表スキーマと関連付けられていないため、行内および行外の一時LOBという概念はありません。ユーザーが一時LOBインスタンスを作成すると、エンジンによってLOBデータへのロケータが作成され戻されます。PL/SQLのDBMS_LOBパッケージ、PRO*C/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参照は、各ユーザー固有のセッションに限定されます。別の場所のロケータを使用するユーザーは、同じLOBIDを持つ自分のセッション内でのみ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言語リファレンス』を参照してください。

ルールおよび制限

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

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

• 最大LOBサイズ

• 最大バッファ・サイズ

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

• Oracle Databaseでは、LOBタイプの列または属性に対する制約はサポートされていませんが、例外としてLOBの列または属性に対するNOT NULL制約はサポートされています。

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

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

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

  マルチバイトのキャラクタ・セットでは、これらのオフセットを正しく解釈できません。結果として、SUBSTRでは、ORA-22998: CLOB or NCLOB in multibyte character set not supportedというエラーが発生します。

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

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

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

  3. offset、amount、newlen、nthの値は、いずれのDBMS_LOBサブプログラムの場合でも、最大値は^lobmaxsize 18446744073709551615(264)です。

  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バイトです。

バッファ・サイズをバイトで表現するBLOBでは、バイト数の上限は32767です。

バッファ・サイズを文字で表現するCLOBまたはNCLOBでは、文字数によるバッファの上限は32767バイトです。たとえば、固定幅の2バイト文字を使用する場合、(20000*2 = 40000は32767より大きいため)20000文字はエラーになります。

例外

表88-8 DBMS_LOBの例外

例外	コード	説明
ACCESS_ERROR	22925	LOBに書き込むデータが多すぎます。LOBサイズは最大4GBです。
BUFFERING_ENABLED	22279	LOBバッファを有効にした状態では操作を実行できません。
CONTENTTYPE_TOOLONG	43859	contenttype文字列の長さが、定義されている最大長を超えています。contenttype文字列の長さを変更し、操作を再試行してください。
CONTENTTYPEBUF_WRONG	43862	contenttypeバッファの長さが、定義されている定数より短くなっています。contenttypeバッファの長さを変更し、操作を再試行してください。
INVALID_ARGVAL	21560	引数はNULL以外の有効な値であることが必要ですが、渡された引数値はNULL、無効または範囲外です。
INVALID_DIRECTORY	22287	現行の操作に使用しているディレクトリは、それが初めてアクセスされたか、または前回のアクセス以降にDBAによって変更された場合は無効です。
NO_DATA_FOUND	1403	ループ読取り操作用の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_*操作を実行しようとしました。
UNOPENED_FILE	22289	要求された操作の実行に使用するファイルがオープンされていません。
VALUE_ERROR	6502	サブプログラムのパラメータの値が無効のため、PL/SQLエラーが発生しました。

DBMS_LOBサブプログラムの要約

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

サブプログラム	説明
APPENDプロシージャ	ソースLOBのコンテンツを宛先LOBに追加します。
CLOSEプロシージャ	オープンしている内部または外部LOBをクローズします。
COMPAREファンクション	2つのLOB全体、または2つのLOBの一部を比較します。
CONVERTTOBLOBプロシージャ	ソースCLOBまたはNCLOBインスタンスから、文字データを読み取り、指定した文字に変換して、変換したデータをバイナリ形式で宛先BLOBインスタンスに書き込み、新しいオフセットを戻します。
CONVERTTOCLOBプロシージャ	ソースBLOBインスタンスを取得し、指定した文字を使用して、ソース・インスタンスのバイナリ・データを文字データに変換し、文字データを宛先CLOBまたはNCLOBインスタンスに書き込み、新しいオフセットを戻します。
COPYプロシージャ	ソースLOBの全体または一部を宛先LOBにコピーします。
COPY_DBFS_LINKプロシージャ	ソースLOBのDBFSリンクを宛先LOBにコピーします。
COPY_FROM_DBFS_LINK	LOBのデータをDBFSストアから取得します。
CREATETEMPORARYプロシージャ	一時BLOBまたはCLOBおよびそれに対応する索引をユーザーのデフォルト一時表領域に作成します。
DBFS_LINK_GENERATE_PATHファンクション	DBFSリンクの作成に使用する一意のファイル・パス名を戻します。
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を解放します。
GET_DBFS_LINKファンクション	指定したSecureFileに関連付けられたDBFSリンク・パスを戻します。
GET_DBFS_LINK_STATEプロシージャ	指定したSecureFileの現在のDBFSリンク状態を取得します。
GETCHUNKSIZEファンクション	LOB値を格納するLOBチャンクの使用領域容量を戻します。
GETCONTENTTYPEファンクション	SETCONTENTTYPEプロシージャを使用して以前設定したコンテンツID文字列を戻します。
GETLENGTHファンクション	LOB値の長さを取得します。
GETOPTIONSファンクション	特定のLOBのoption_typeフィールドに対応する設定を取得します。
GET_STORAGE_LIMITファンクション	データベース構成のLOBの記憶域制限を戻します。
INSTRファンクション	LOBにあるパターンのn番目の一致のマッチング位置を戻します。
ISOPENファンクション	LOBが入力ロケータを使用して、すでにオープンされたかどうかをチェックします。
ISSECUREFILEファンクション	渡されるLOBロケータがSecurefiles LOB用の場合にTRUEを戻します。それ以外の場合は、FALSEを戻します。
ISTEMPORARYファンクション	ロケータが一時LOBをポイントしているかどうかをチェックします。
LOADBLOBFROMFILEプロシージャ	BFILEデータを内部BLOBにロードします。
LOADCLOBFROMFILEプロシージャ	BFILEデータを内部CLOBにロードします。
LOADFROMFILEプロシージャ	BFILEデータを内部LOBにロードします。
MOVE_TO_DBFS_LINKプロシージャ	指定したSecureFileデータをDBFSストアに書き込みます。
OPENプロシージャ	指定されたモードでLOB(内部、外部またはテンポラリ)をオープンします。
READプロシージャ	指定されたオフセット以降のLOBデータを読み込みます。
SET_DBFS_LINKプロシージャ	指定したSecureFileを指定したパス名にリンクします。データはパスにコピーされません。
SETCONTENTTYPEプロシージャ	LOB内のデータのコンテンツ・タイプ文字列値を設定します。
SETOPTIONSプロシージャ	LOB単位でCSCE機能を使用可能にして、デフォルトのLOB列設定より優先させます。
SUBSTRファンクション	指定されたオフセット以降のLOB値の一部を戻します。
TRIMプロシージャ	指定された長さまでLOB値を切り捨てます。
WRITEプロシージャ	指定されたオフセットからLOBにデータを書き込みます。
WRITEAPPENDプロシージャ	LOBの終わり以降にバッファを書き込みます。

APPENDプロシージャ

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

構文

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

パラメータ

表88-10 APPENDプロシージャのパラメータ

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

例外

表88-11 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文の中に囲むことをお薦めします。

• アーカイブされているLOBでAPPENDをコールした場合は、最初のバイトが書き込まれる前にLOBが暗黙的に取得されます。

• DBFSリンクであるSecureFiles LOBでAPPENDがコールされると、例外が発生します。

関連項目: このプロシージャの使用方法の詳細は、『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); 

パラメータ

表88-12 CLOSEプロシージャのパラメータ

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

例外

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

使用上の注意

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

オープン/クローズ・インタフェース内のすべての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);

パラメータ

表88-13 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(ゼロ)以外の整数が戻されます。

• amount、offset_1またはoffset_2のいずれかが有効なLOBオフセット値でない場合はNULLが戻されます。有効なオフセットは、1からLOBMAXSIZEの範囲内です。

使用上の注意

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

• offsetおよびamountパラメータによって指定した範囲のデータがすべて完全に一致すると、COMPAREにより0(ゼロ)が戻されます。1番目のCLOBが2番目より小さいと、COMPAREによって-1が戻され、大きいと1が戻されます。

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

• アーカイブされているLOBでCOMPAREをコールした場合は、比較が開始される前にLOBが暗黙的に取得されます。

• DBFSリンクであるSecureFiles LOBでCOMPARE()がコールされると、リンクされたLOBは、可能な場合はDBFSからストリーミングされ、可能でない場合は例外が発生します。

例外

表88-14 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); 

パラメータ

表88-15 CONVERTTOBLOBプロシージャのパラメータ

パラメータ	説明
dest_lob	宛先LOBインスタンスのLOBロケータ。
src_clob	ソース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パラメータに変数または値を渡す必要があります。

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

表88-16 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を指定します。

• CONVERTTOBLOBは、データの変換および書込み前に、必要に応じてソースまたは宛先LOBを取得します。

例外

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

表88-17 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);

パラメータ

表88-18 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パラメータに変数または値を渡す必要があります。

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

表88-19 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パラメータにソースLOBの目的のキャラクタ・セットを指定する必要があります。blob_csidには0(ゼロ)の値を渡せます。そうすると、データベースで、目的のキャラクタ・セットが宛先LOBキャラクタ・セットと同じであるとみなされます。

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

• CONVERTTOCLOBは、データの変換および書込み前に、必要に応じてソースまたは宛先LOB(あるいはその両方)を取得します。

例外

表88-20 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);

パラメータ

表88-21 COPYプロシージャのパラメータ

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

例外

表88-22 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文の中に囲むことをお薦めします。

• コピー前に、ソースおよび宛先LOBが現在アーカイブされている場合は、それらが取得されます。完全に上書きする場合、宛先LOBは取り出されません。

• ソースLOBがDBFSリンクの場合、データは、可能な場合はDBFSからストリーミングされ、可能でない場合は例外が発生します。宛先LOBがDBFSリンクの場合は、例外が発生します。

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

COPY_DBFS_LINKプロシージャ

このプロシージャは、ソースLOBのDBFSリンクを宛先LOBにコピーします。

構文

DBMS_LOB.COPY_DBFS_LINK (
  lob_loc_dst    IN OUT BLOB,
  lob_loc_src    IN     BLOB,
  flags          IN     PLS_INTEGER DEFAULT DBFS_LINK_NOCACHE);

DBMS_LOB.COPY_DBFS_LINK (
  lob_loc_dst    IN OUT CLOB CHARACTER SET ANY_CS,
  lob_loc_src    IN     CLOB CHARACTER SET ANY_CS,
  flags          IN     PLS_INTEGER DEFAULT DBFS_LINK_NOCACHE);

パラメータ

表88-23 COPY_DBFS_LINKプロシージャのパラメータ

パラメータ	説明
lob_loc_dst	lob_loc_srcと同じ記憶域データを参照するように設定されるLOB。
lob_loc_src	参照のコピー元のLOB。
flags	COPY_DBFS_LINKのオプション: DBFS_LINK_NOCACHEは、DBFSリンクのみをコピーするように指定します。 DBFS_LINK_CACHEは、DBFSリンクをコピーし、lob_loc_dstによって指定されているデータベースLOBにデータを読み込んで、データがキャッシュされるように指定します。

例外

表88-24 COPY_DBFS_LINKプロシージャの例外

例外	説明
SECUREFILE_BADLOB	lob_loc_srcまたはlob_loc_dstは、SECUREFILEではありません。
INVALID_ARGVAL	lob_loc_src LOBはアーカイブされていません。
ORA-01555	ソースLOBがすでに取得されているか、アーカイブされていないか、またはロケータの取得後にLOBが(変更されたかどうかに関係なく)移行されています。

COPY_FROM_DBFS_LINK

このプロシージャは、アーカイブされたSecureFiles LOBデータをDBFS HSMストアから取得し、データベースにコピーします。

構文

DBMS_LOB.COPY_FROM_DBFS_LINK (
  lob_loc       IN OUT BLOB);

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

パラメータ

表88-25 COPY_FROM_DBFS_LINKプロシージャのパラメータ

パラメータ	説明
lob_loc	アーカイブから取得されるLOB

使用上の注意

COPY_FROM_DBFS_LINKによって基礎となるDBFSファイルは削除されません。

LOBが正常に取得されると、COPY_FROM_DBFS_LINKでは暗黙的に成功が返されます。

例外

表88-26 COPY_FROM_DBFS_LINKプロシージャの例外

例外	説明
SECUREFILE_BADLOB	lob_locはSECUREFILEではありません。
ORA-01555	LOBがすでに取得されており、取得後に変更されているかどうか、ロケータの取得後にLOBが(変更されたかどうかに関係なく)移行されているかどうか。

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

パラメータ

表88-27 CREATETEMPORARYプロシージャのパラメータ

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

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

DBFS_LINK_GENERATE_PATHファンクション

このサブプログラムは、DBFSリンクの作成に使用する一意のファイル・パス名を戻します。

構文

DBMS_LOB.DBFS_LINK_GENERATE_PATH (
  lob_loc       IN BLOB,
  storage_dir   IN VARCHAR2) 
 RETURN VARCHAR2;
 
DBMS_LOB.DBFS_LINK_GENERATE_PATH (
  lob_loc       IN CLOB CHARACTER SET ANY_CS,
  storage_dir   IN VARCHAR2) 
 RETURN VARCHAR2;

プラグマ

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

パラメータ

表88-28 DBFS_LINK_GENERATE_PATHファンクションのパラメータ

パラメータ	説明
lob_loc	DBFSから取得されるLOB。
storage_dir	ファイルの親ディレクトリとなるDBFSディレクトリ。

例外

表88-29 DBFS_LINK_GENERATE_PATHファンクションの例外

例外	説明
SECUREFILE_WRONGTYPE	lob_locはSECUREFILEではありません。

使用上の注意

アーカイブに使用できるグローバルに一意なファイル・パス名を戻します。これは、このファンクションの各種LOBまたはLOBの各バージョンを対象としたすべてのコールで、グローバルに一意であることが保証されています。同一のLOBおよびバージョンでは、常に同じ名前になります。

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

パラメータ

表88-30 ERASEプロシージャのパラメータ

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

使用上の注意

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

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

• ERASEは、アーカイブされているLOBを取得します。ただし、消去がLOB全体に適用される場合を除きます。

• 削除するLOBがDBFSリンクの場合、例外が発生します。

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

例外

表88-31 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); 

パラメータ

表88-32 FILECLOSEプロシージャのパラメータ

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

例外

表88-33 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; 

例外

表88-34 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);

パラメータ

表88-35 FILEEXISTSファンクションのパラメータ

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

戻り値

表88-36 FILEEXISTSファンクションの戻り値

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

例外

表88-37 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); 

パラメータ

表88-38 FILEGETNAMEプロシージャのパラメータ

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

例外

表88-39 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);

パラメータ

表88-40 FILEISOPENファンクションのパラメータ

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

戻り値

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

使用上の注意

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

例外

表88-41 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); 

パラメータ

表88-42 FILEOPENプロシージャのパラメータ

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

例外

表88-43 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);

パラメータ

表88-44 FRAGMENT_DELETEプロシージャのパラメータ

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

例外

表88-45 FRAGMENT_DELETEプロシージャの例外

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

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

パラメータ

表88-46 FRAGMENT_INSERTプロシージャのパラメータ

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

例外

表88-47 FRAGMENT_INSERTプロシージャの例外

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

使用上の注意

FRAGMENT_INSERTは、LOBに対する操作を実行する前に、必要に応じて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);

パラメータ

表88-48 FRAGMENT_MOVEプロシージャのパラメータ

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

例外

表88-49 FRAGMENT_MOVEプロシージャの例外

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

使用上の注意

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

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

• FRAGMENT_MOVEは、LOBに対する操作を実行する前に、必要に応じてLOBを取得します。

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

パラメータ

表88-50 FRAGMENT_REPLACEファンクションのパラメータ

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

例外

表88-51 FRAGMENT_REPLACEプロシージャの例外

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

使用上の注意

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

• FRAGMENT_REPLACEは、LOBに対する操作を実行する前に、必要に応じて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); 

パラメータ

表88-52 FREETEMPORARYプロシージャのパラメータ

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

使用上の注意

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

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

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

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

GET_DBFS_LINKファンクション

このファンクションは、指定したSecureFile LOBのDBFSパス名を戻します。

構文

DBMS_LOB.GET_DBFS_LINK (
  lob_loc             IN     BLOB,
  storage_path        OUT VARCHAR2(DBFS_LINK_PATH_MAX_SIZE),
  lob_length          OUT NUMBER);

DBMS_LOB.GET_DBFS_LINK (
  lob_loc             IN     CLOB CHARACTER SET ANY_CS,
  storage_path        OUT VARCHAR2(DBFS_LINK_PATH_MAX_SIZE),
  lob_length          OUT NUMBER);

パラメータ

表88-53 GET_DBFS_LINKファンクションのパラメータ

パラメータ	説明
lob_loc	DBFSから取得されるLOB。
storage_path	DBFSに格納されているLOBへのパス。
lob_length	DBFSへの書込み時点でのLOBの長さ。

戻り値

アーカイブID。

例外

表88-54 GET_DBFS_LINKファンクションの例外

例外	説明
SECUREFILE_BADLOB	lob_locはSECUREFILEではありません。
ORA-01555	LOBがすでに取得されており、取得後に変更されている。または、ロケータの取得後にLOBが(変更されたかどうかに関係なく)移行されている。

GET_DBFS_LINK_STATEプロシージャ

このプロシージャは、指定したSecureFileの現在のリンク状態を取得します。

構文

DBMS_LOB.GET_DBFS_LINK_STATE (
  lob_loc       IN BLOB,
  storage_path  OUT VARCHAR2(DBFS_LINK_PATH_MAX_SIZE),
  state         OUT NUMBER,
  cached        OUT BOOLEAN);

DBMS_LOB.GET_DBFS_LINK_STATE (
  lob_loc       IN CLOB CHARACTER SET ANY_CS,
  storage_path  OUT VARCHAR2(DBFS_LINK_PATH_MAX_SIZE),
  state         OUT NUMBER,
  cached        OUT BOOLEAN);

パラメータ

表88-55 GET_DBFS_LINK_STATEプロシージャのパラメータ

パラメータ	説明
lob_loc	アーカイブから取得されるLOB
storage_path	DBFS HSMストアに格納されているLOBへのパス。
state	DBFS_LINK_NEVER、DBFS_LINK_NOまたはDBFS_LINK_YESのいずれか
cached	LOBがアーカイブされており、アーカイブ時にキャッシュされるように指定されている場合。

例外

表88-56 GET_DBFS_LINK_STATEプロシージャの例外

例外	説明
SECUREFILE_BADLOB	lob_locはSECUREFILEではありません。

使用上の注意

• LOBがアーカイブされていない場合、状態はDBMS_LOB.DBFS_LINK_NEVERに設定されます。LOBがアーカイブされている場合、状態はDBMS_LOB.DBFS_LINK_YESに設定されます。LOBが以前にアーカイブから取得されている場合、状態はDBFS_LINK_NOに設定されます。

• LOBがアーカイブされたにもかかわらず、RDBMSに残されている場合、cachedはTRUEに設定されます。データがリンクの作成後に削除された場合、cachedはFALSEに設定され、状態がDBMS_LOB.DBFS_LINK_NEVERの場合はNULLに設定されます。

GETCONTENTTYPEファンクション

このプロシージャは、SETCONTENTTYPEプロシージャを使用して以前設定したコンテンツ・タイプ文字列を戻します。

構文

DBMS_LOB.GETCONTENTTYPE (
   lob_loc  IN BLOB)
 RETURN VARCHAR2;

DBMS_LOB.GETCONTENTTYPE (
   lob_loc  IN CLOB CHARACTER SET ANY_CS)
 RETURN VARCHAR2;

プラグマ

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

パラメータ

表88-57 GETCONTENTTYPEファンクションのパラメータ

パラメータ	説明
lob_loc	コンテンツ・タイプを取得するLOB。

戻り値

戻されたコンテンツ・タイプ。

SecureFiles LOBにcontenttypeが関連付けられていない場合、GETCONTENTTYPE()はNULLを戻します。

例外

表88-58 GETCONTENTTYPEファンクションの例外

例外	説明
SECUREFILE_BADLOB	lob_locはSECUREFILEではありません。

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

パラメータ

表88-59 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); 

パラメータ

表88-60 GETCHUNKSIZEファンクションのパラメータ

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

戻り値

戻り値は、使用可能なチャンク・サイズ(バイト単位)です。

使用上の注意

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

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

• チャンク・サイズはLOBタイプ(BLOB、CLOB、NCLOB、Unicodeまたはその他のキャラクタ・セット)とは無関係です。

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

例外

表88-61 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);

パラメータ

表88-62 GETLENGTHファンクションのパラメータ

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

戻り値

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

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

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

  
  

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

  
  

例外

表88-63 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 CHARACTER SET ANY_CS,
  option_types        IN     PLS_INTEGER) 
RETURN PLS_INTEGER;

パラメータ

表88-64 GETOPTIONSファンクションのパラメータ

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

戻り値

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

例外

表88-65 GETOPTIONSプロシージャの例外

例外	説明
INVALID_ARGVAL	パラメータ値が無効でした。
QUERY_WRITE	問合せ時に操作を実行できません。
BUFFERING_ENABLED	LOBバッファを有効にした状態では操作を実行できません。
SECUREFILE_BADLOB	SECUREFILE LOBのみのコールで、SECUREFILE以外のLOBが使用されました。

使用上の注意

圧縮または複製解除の機能が備えられていないSecureFile列に対して、これらの機能をオンまたはオフにすることはできません。GetOptionsファンクションとSETOPTIONSプロシージャは、個々のSecureFilesに対して動作します。特定のSecureFileの機能をオフにしたり、SetOptionsによってすでにオフにされている機能をオンにすることはできますが、表の作成時にSecureFileに指定されていないオプションをオンにすることはできません。

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

パラメータ

表88-66 INSTRファンクションのパラメータ

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

戻り値

表88-67 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)はサポートされていません。

例外

表88-68 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); 

パラメータ

表88-69 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およびラージ・オブジェクト開発者ガイド』を参照してください。

ISSECUREFILEファンクション

このファンクションは、渡されるLOBロケータがSecurefile LOB用の場合にTRUEを戻します。そうでなければ、FALSEを戻します。

構文

DBMS_LOB ISSECUREFILE(
    lob_loc    IN      BLOB)
  RETURN BOOLEAN;

プラグマ

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

パラメータ

表88-70 ISSECUREFILEファンクションのパラメータ

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

戻り値

このファンクションは、渡されるLOBロケータがSecurefile LOB用の場合にTRUEを戻します。そうでなければ、FALSEを戻します。

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

パラメータ

表88-71 ISTEMPORARYプロシージャのパラメータ

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

戻り値

戻り値は、LOBが一時LOBとして存在している場合は1、LOBが一時LOBではないか、存在していない場合は0(ゼロ)、指定されたロケータがNULLの場合はNULLです。

使用上の注意

FREETEMPORARYを指定して一時LOBを解放した場合、LOBロケータはNULLに設定されません。したがって、ISTEMPORARYは、解放後に明示的にNULLに再設定されていないロケータに対して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);

パラメータ

表88-72 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文の中に囲むことをお薦めします。

• LOADFROMFILEは、ロード前に宛先LOBを取得します。ただし、ロードがLOB全体に適用される場合を除きます。

定数およびデフォルト

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

表88-73 パラメータのデフォルト値

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

DBMSLOB.SQLで定義される定数

lobmaxsize                    CONSTANT INTEGER        := DBMS_LOB.LOBMAXSIZE;

例外

表88-74 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);

パラメータ

表88-75 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文字を一連のバイトにマッピングする複数のコード体系が定義されています。表88-76「サポートされているUnicodeコード体系」に、このサブプログラムでサポートされているUnicodeコード体系を示します。

表88-76 サポートされている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にはロードされません。

定数

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

表88-77 パラメータのデフォルト値

パラメータ	デフォルト値	説明
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;

例外

表88-78 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);

パラメータ

表88-79 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の場合はバイト単位、CLOBsの場合は文字単位です。

注意: 入力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キャラクタ・セットにする必要があります。ただし、sql*loaderでは必要なキャラクタ・セット変換が提供されるため、CLOBまたはNCLOBにデータをロードするには、LOADFROMFILEではなくsql*loaderを使用してください。

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

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

例外

表88-80 LOADFROMFILEプロシージャの例外

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

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

MOVE_TO_DBFS_LINKプロシージャ

このプロシージャは、(データベースからの)指定されたLOBデータをDBFS HSMストアにアーカイブします。

構文

DBMS_LOB.MOVE_TO_DBFS_LINK (
  lob_loc       IN OUT BLOB,
  storage_path  IN     VARCHAR2(dbfs_link_path_max_size),
  flags         IN     BINARY INTEGER DEFAULT DBFS_LINK_NOCACHE); 

DBMS_LOB.MOVE_TO_DBFS_LINK (
  lob_loc       IN OUT CLOB CHARACTER SET ANY_CS,
  storage_path  IN     VARCHAR2(dbfs_link_path_max_size),
  flags         IN     BINARY INTEGER DEFAULT DBFS_LINK_NOCACHE);

パラメータ

表88-81 MOVE_TO_DBFS_LINKプロシージャのパラメータ

パラメータ	説明
lob_loc	アーカイブされるLOB。
storage_path	LOBが格納されるパス。
flags	DBFS_LINK_CACHEまたはDBFS_LINK_NOCACHE。DBFS_LINK_CACHEが指定されている場合、LOBデータはDBFSストアに書き込まれると同時に、引き続きRDBMSに格納されます。DBFS_LINK_NOCACHEは、LOBデータがDBFSへの書込み後にRDBMSから削除されるように指定します。

例外

表88-82 MOVE_TO_DBFS_LINKプロシージャの例外

例外	説明
SECUREFILE_BADLOB	lob_locはSECUREFILEではありません。

使用上の注意

• このプロシージャは、LOBがすでにアーカイブされている場合、正常にアーカイブされたときと同様の結果を戻します。その場合、DBFS_LINK_NOCACHEが指定されているか、flagsがデフォルト設定されていると、LOBデータはRDBMSから削除されます。

• 同じLOBで同じフラグを使用してこのプロシージャを複数回コールしても、効果はありません。

• すでにアーカイブされているLOBでこのプロシージャをコールすると、フラグの設定に応じてLOBのキャッシュ(DBFS_LINK_CACHE)または削除(DBFS_LINK_NOCACHE)が実行されます。

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

パラメータ

表88-83 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)の場合、OPENではサーバー側の実際のオペレーティング・システム・ファイルがオープンされるため、ラウンドトリップが必要です。

オープン/クローズ・インタフェース内のすべての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);

パラメータ

表88-84 READプロシージャのパラメータ

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

例外

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

表88-85 READプロシージャの例外

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

表88-86 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値を変換します。

• READは、読取り前に必要に応じてLOBを取得します。

• LOBがDBFSリンクの場合、データは、可能な場合はDBFSからストリーミングされ、可能でない場合は例外が発生します。

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

SET_DBFS_LINKプロシージャ

このファンクションは、指定したSecureFileを指定したパス名にリンクします。データはパスにコピーされません。

構文

DBMS_LOB.SET_DBFS_LINK (
  lob_loc        IN OUT BLOB,
  archive_id     IN     RAW(1024));

DBMS_LOB.SET_DBFS_LINK(
  lob_loc_dst    IN OUT CLOB CHARACTER SET ANY_CS,
  archive_id     IN     RAW(1024));

パラメータ

表88-87 SET_DBFS_LINKプロシージャのパラメータ

パラメータ	説明
lob_loc	参照値を格納するLOB。
archive_id	いずれかのGET_DBFS_LINKファンクションをコールすると戻されるアーカイブID。

例外

表88-88 SET_DBFS_LINKプロシージャの例外

例外	説明
SECUREFILE_BADLOB	lob_locはSECUREFILEではありません。

SETCONTENTTYPEプロシージャ

このプロシージャは、LOB内のデータのコンテンツ・タイプ文字列値を設定します。

構文

DBMS_LOB.SETCONTENTTYPE (
   lob_loc      IN OUT NOCOPY BLOB,
   contenttype  IN            VARCHAR2);

DBMS_LOB.SETCONTENTTYPE (
   lob_loc     IN OUT NOCOPY CLOB CHARACTER SET ANY_CS,
   contenttype IN            VARCHAR2);

パラメータ

表88-89 SETCONTENTTYPEプロシージャのパラメータ

パラメータ	説明
lob_loc	コンテンツ・タイプを割り当てるLOB。
contenttype	割り当てる文字列。

例外

表88-90 SETCONTENTTYPEプロシージャの例外

例外	説明
SECUREFILE_BADLOB	lob_locはSECUREFILEではありません。

使用上の注意

SECUREFILEに関連付けられている既存のコンテンツ・タイプを消去するには、contenttypeを空の文字列に設定してSETCONTENTTYPEを起動します。

SETOPTIONSプロシージャ

このプロシージャは、デフォルトのLOB列の設定を上書きする、圧縮および重複除外を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);

パラメータ

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

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

例外

表88-92 SETOPTIONSプロシージャの例外

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

使用上の注意

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

• 表の作成時に圧縮または重複除外の機能が設定されていない場合、これらの機能をSecureFile列に対してオンまたはオフにすることはできません。

  GETOPTIONSファンクションとSETOPTIONSプロシージャは、個々のSecureFileに対して動作します。特定のSecureFile LOBに対する圧縮または重複除外をオフにしたり、SETOPTIONSによってすでにオフにされている場合はオンにすることができます。

• このコールでは、変更を永続化させる際にサーバーへのラウンドトリップが発生します。

SUBSTRファンクション

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

固定幅のnバイトのCLOBの場合、SUBSTRに対する入力amountの指定が(32767/n)を超えると、SUBSTRでは、(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);

パラメータ

表88-93 SUBSTRファンクションのパラメータ

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

戻り値

表88-94 SUBSTRファンクションの戻り値

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

例外

表88-95 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値を変換します。

• DBMS_LOB.SUBSTRは、LOBに格納されている文字に基づいて8191個以上の文字を戻します。使用可能なバッファを超える文字バイト数が原因ですべての文字が戻されない場合、新しいオフセットでDBMS_LOB.SUBSTRをコールして残りの文字を読み取るか、すべてのデータを抽出するまでサブプログラムのコールをループする必要があります。

• SUBSTRは、読取り前に必要に応じてLOBを取得します。

• LOBがDBFSリンクの場合、データは、可能な場合はDBFSからストリーミングされ、可能でない場合は例外が発生します。

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

TRIMプロシージャ

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

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

空のLOBに対してTRIMを実行すると、何も処理は行われず、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);

パラメータ

表88-96 TRIMプロシージャのパラメータ

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

例外

表88-97 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文の中に囲むことをお薦めします。

• TRIMは、LOBの長さを変更する前に、必要に応じてLOBを取得します。ただし、指定する新しい長さが0(ゼロ)の場合を除きます。

関連項目: 「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); 

パラメータ

表88-98 WRITEプロシージャのパラメータ

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

例外

表88-99 WRITEプロシージャの例外

例外	説明
VALUE_ERROR	lob_loc、amountまたはoffsetパラメータのいずれかがNULL、範囲外またはINVALIDです。
INVALID_ARGVAL	次のいずれかです。 - amount < 1 - amount > 32767 bytes (or the character equivalent) - 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文の中に囲むことをお薦めします。

• WRITEは、LOBに書き込む前に、必要に応じてLOBを取得します。ただし、書込みがLOB全体を上書きするように指定されている場合を除きます。

関連項目: 「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); 

パラメータ

表88-100 WRITEAPPENDプロシージャのパラメータ

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

使用上の注意

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

例外

表88-101 WRITEAPPENDプロシージャの例外

例外	説明
VALUE_ERROR	lob_loc、amountまたはoffsetパラメータのいずれかがNULL、範囲外またはINVALIDです。
INVALID_ARGVAL	次のいずれかです。 - amount < 1 - amount > 32767 bytes (or the character equivalent)
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文の中に囲むことをお薦めします。

• WRITEAPPENDは、LOBに追加する前に、必要に応じてLOBを取得します。

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