DBMS_LOB
パッケージは、BLOB
、CLOB
、NCLOB
、BFILE
および一時LOB
を操作するサブプログラムを提供します。DBMS_LOB
を使用すると、各LOB
の特定の部分またはLOB
全体に対するアクセスおよび操作ができます。
関連項目: 『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』 |
この章では、次の項目について説明します。
概要
セキュリティ・モデル
定数
データ・タイプ
使用上の注意
ルールおよび制限
例外
このパッケージは、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パッケージでは、次の表に示す定数が使用されます。
表82-1 DBMS_LOBの定数 - 基本
定数 | タイプ | 値 | 説明 |
---|---|---|---|
|
|
|
コール継続時間を含む |
|
|
|
指定した |
|
|
|
指定した |
|
|
|
指定した |
|
|
18446744073709551615 |
|
|
|
|
セッション継続時間を含む |
表82-2 DBMS_LOBの定数 - オプション・タイプ
定数 | 定義 | 値 | 説明 |
---|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
表82-3 DBMS_LOBの定数 - オプション値
定数 | 定義 | 値 | 説明 |
---|---|---|---|
|
|
|
SETOPTIONSプロシージャに対しては、圧縮をオフに設定します。GETOPTIONSファンクションに対しては、圧縮はオフになっています。 |
|
|
|
SETOPTIONSプロシージャに対しては、圧縮をオンに設定します。GETOPTIONSファンクションに対しては、圧縮はオンになっています。 |
|
|
|
SETOPTIONSプロシージャに対しては、重複除外をオフに設定します。GETOPTIONSファンクションに対しては、重複除外はオフになっています。 |
|
|
|
SETOPTIONSプロシージャに対しては、重複除外をオンに設定します。GETOPTIONSファンクションに対しては、重複除外はオンになっています。 |
|
|
|
GETOPTIONSファンクションに対しては、暗号化はオフになっています。 |
|
|
|
GETOPTIONSファンクションに対しては、暗号化はオンになっています。 |
表82-4 DBMS_LOBの定数 - DBFS状態値のタイプ
定数 | 定義 | 値 | 説明 |
---|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
DBMS_LOB
パッケージでは、表82-7に示すデータ・タイプが使用されます。
表82-7 DBMS_LOBで使用されるデータ・タイプ
タイプ | 説明 |
---|---|
|
ソースまたは宛先のバイナリ |
|
ソースまたは宛先の |
|
ソースまたは宛先の文字 |
|
ソースまたは宛先の文字バッファ( |
|
バッファまたは |
|
データベースの外部に格納されているラージ・バイナリ・オブジェクト。 |
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
(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の場合は、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
参照は、各ユーザー固有のセッションに限定されます。別の場所のロケータを使用するユーザーは、同じLOB
IDを持つ自分のセッション内でのみLOBにアクセスできます。ユーザーがこれを試行することはお薦めしませんが、試行した場合でも他のユーザーのデータに影響を与えることはありません。
データベースは、V$TEMPORARY_LOBS
と呼ばれるv$
ビューにセッションごとの一時LOBを記録しますが、このビューには、セッションごとに存在している一時LOB数に関する情報が含まれています。V$
ビューは、DBAが使用するためのものです。セッションから、データベースはどのユーザーが一時LOBを所有しているかを判断できます。V$TEMPORARY_LOBS
をDBA_SEGMENTS
と組み合せて使用することで、DBAは、セッションで一時LOB用に使用されている領域の量を把握できます。これらの表を使用すると、DBAは一時LOBが使用している一時領域の緊急クリーンアップを監視して指示できます。
一時LOBに固有の注意事項は次のとおりです。
DBMS_LOB
のすべてのファンクションは、入力パラメータのいずれかがNULL
の場合、NULL
を戻します。LOB
ロケータがNULL
として入力されると、DBMS_LOB
のすべてのプロシージャで例外が発生します。
CLOB
に基づく操作では、パラメータ(CLOB
パラメータやVARCHAR2
のバッファとパターンなど)のキャラクタ・セットIDが一致しているかどうかは検証されません。この確認はユーザーが各自で行ってください。
データ記憶域リソースは、DBAが異なるテンポラリ表領域を作成して制御します。必要に応じて、DBAはユーザーごとに別々のテンポラリ表領域を定義できます。
関連項目: NOCOPY 構文の詳細は、『Oracle Database PL/SQL言語リファレンス』を参照してください。 |
Oracle Databaseでは、LOBタイプの列または属性に対する制約はサポートされていませんが、例外としてLOBの列または属性に対するNOT NULL
制約はサポートされています。
このパッケージにあるサブプログラムの仕様部に適用される規則は次のとおりです。
BLOB
およびBFILE
を操作するサブプログラムのlength
、offset
およびamount
パラメータは、バイト単位で指定する必要があります。
CLOB
を操作するサブプログラムのlength
、offset
およびamount
パラメータは、文字単位で指定する必要があります。
マルチバイトのキャラクタ・セットでは、これらのオフセットを正しく解釈できません。結果として、SUBSTR
では、ORA-22998: CLOB or NCLOB in multibyte character set not supported
というエラーが発生します。
パラメータ値の指定時に次の制限事項に従わなかった場合(またはパラメータ値を指定しなかった場合)は、INVALID_ARGVAL
例外が発生します。
LOB
データの開始位置からの正の絶対オフセットのみ許可されています。LOB
の終了位置からの負のオフセットは許可されていません。
amount
、offset
、newlen
、nth
など、サイズおよび位置を表すパラメータには、0(ゼロ)以外の正の値のみ許可されています。SQL文字列ファンクションおよび演算子で確認される負のオフセットおよび範囲は許可されていません。
offset
、amount
、newlen
、nth
の値は、いずれのDBMS_LOB
サブプログラムの場合でも、最大値はlobmaxsize
18446744073709551615(264)です。
固定幅のマルチバイト・キャラクタで構成される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
を含んだ行のロックは暗黙的には行われません。
サブプログラム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ブロック内でオープンされたファイルは、ブロックの正常終了または異常終了の前にクローズしてください。
表82-8 DBMS_LOBの例外
例外 | コード | 説明 |
---|---|---|
|
|
LOBに書き込むデータが多すぎます。LOBサイズは最大4GBです。 |
|
|
LOBバッファを有効にした状態では操作を実行できません。 |
|
|
|
|
|
|
|
|
引数は |
|
|
現行の操作に使用しているディレクトリは、それが初めてアクセスされたか、または前回のアクセス以降にDBAによって変更された場合は無効です。 |
|
|
ループ読取り操作用の |
|
|
ファイルに指定されているディレクトリが存在しません。 |
|
|
ユーザーに、そのディレクトリまたはファイルの操作に必要なアクセス権限がありません。 |
|
|
オープン・ファイル数が最大値に達しました。 |
|
|
ファイル操作に失敗しました。 |
|
|
問合せまたはPDMLスレーブ内でLOB書込みを実行できません。 |
|
|
|
|
|
|
|
|
|
|
|
LOBの終わりを超えて |
|
|
要求された操作の実行に使用するファイルがオープンされていません。 |
|
|
サブプログラムのパラメータの値が無効のため、PL/SQLエラーが発生しました。 |
表82-9 DBMS_LOBパッケージのサブプログラム
サブプログラム | 説明 |
---|---|
|
ソース |
|
オープンしている内部または外部 |
|
2つの |
|
ソース |
|
ソース |
|
ソース |
|
ソース |
|
LOBのデータをDBFSストアから取得します。 |
|
一時 |
DBFS_LINK_GENERATE_PATHファンクション |
DBFSリンクの作成に使用する一意のファイル・パス名を戻します。 |
|
|
|
ファイルをクローズします。 |
|
オープンしているファイルをすべてクローズします。 |
|
ファイルがサーバー上に存在しているかどうかをチェックします。 |
ディレクトリ・オブジェクト名およびファイル名を取得します。 |
|
|
入力 |
|
ファイルをオープンします。 |
|
|
|
指定したデータ(最大32K)を、 |
|
指定したオフセット位置から新しく指定したオフセット位置に、バイト単位( |
|
指定したオフセット位置にあるデータを指定したデータ(32k以下)で置き換えます。 |
|
デフォルト一時表領域にある一時 |
|
指定したSecureFileに関連付けられたDBFSリンク・パスを戻します。 |
|
指定したSecureFileの現在のDBFSリンク状態を取得します。 |
|
|
|
SETCONTENTTYPEプロシージャを使用して以前設定したコンテンツID文字列を戻します。 |
|
LOB値の長さを取得します。 |
|
特定の |
|
データベース構成のLOBの記憶域制限を戻します。 |
|
|
|
|
|
ロケータが一時 |
|
|
|
|
|
|
|
指定したSecureFileデータをDBFSストアに書き込みます。 |
|
指定されたモードで |
|
指定されたオフセット以降の |
|
指定したSecureFileを指定したパス名にリンクします。データはパスにコピーされません。 |
|
LOB内のデータのコンテンツ・タイプ文字列値を設定します。 |
|
LOB単位でCSCE機能を使用可能にして、デフォルトのLOB列設定より優先させます。 |
|
指定されたオフセット以降の |
|
|
|
|
|
|
このプロシージャは、ソース内部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);
使用上の注意
オープン/クローズ・インタフェース内のLOB
操作のラップは必須ではありません。操作を実行する前にLOB
をオープンしなかった場合、LOB
列のファンクション索引およびドメイン索引は、コール中に更新されます。ただし、操作を実行する前にLOB
をオープンした場合は、トランザクションのコミットを実行する前にクローズする必要があります。内部LOB
がクローズされるときに、LOB
列のファンクション索引およびドメイン索引が更新されます。
オープン/クローズAPI内のLOB
操作をラップしなかった場合、ファンクション索引およびドメイン索引はLOB
へ書き込むたびに更新されます。これにより、パフォーマンスに悪影響を及ぼす可能性があります。したがって、LOB
への書込み操作をOPEN
またはCLOSE
文の中に囲むことをお薦めします。
アーカイブされているLOB
でAPPEND
をコールした場合は、最初のバイトが書き込まれる前にLOB
が暗黙的に取得されます。
関連項目: このプロシージャの使用方法の詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください。 |
このプロシージャは、オープンしている内部または外部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);
使用上の注意
CLOSE
では、内部または外部LOBのいずれの場合もサーバーへのラウンドトリップが必要です。内部LOBの場合、CLOSE
はクローズ・コールに依存するその他のコードをトリガーし、外部LOB (BFILE
)の場合、CLOSE
はサーバー側のオペレーティング・システム・ファイルを実際にクローズします。
オープン/クローズ・インタフェース内のすべてのLOB
操作のラップは必須ではありません。ただし、LOB
をオープンしている場合は、トランザクションのコミットを実行する前にクローズする必要があり、クローズしない場合は、エラーが発生します。内部LOB
がクローズされるときに、LOB
列のファンクション索引およびドメイン索引が更新されます。
トランザクションによってオープンされたすべてのLOBをクローズする前にトランザクションをコミットすると、エラーが発生します。エラーが戻された場合、LOBのオープンは廃棄されますが、トランザクションのコミットは正常に行われます。したがって、そのトランザクションにおけるLOB
および非LOB
データの変更はすべてコミットされますが、ドメイン索引およびファンクションベースの索引は更新されません。このような場合は、LOB
列のファンクション索引およびドメイン索引を再構築する必要があります。
関連項目: このプロシージャの使用方法の詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください。 |
このファンクションは、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;
戻り値
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
が暗黙的に取得されます。
例外
表82-14 BFILE操作に関するCOMPAREファンクションの例外
例外 | 説明 |
---|---|
|
ファイルが入力ロケータを使用してオープンされていません。 |
|
ディレクトリが存在しません。 |
|
ディレクトリに対する権限がありません。 |
|
ディレクトリがファイルのオープン後に無効となりました。 |
|
ファイルが存在しないか、またはファイルのアクセス権限がありません。 |
|
いずれかのLOBでバッファが有効になっている場合、LOBバッファを有効にした状態では操作を実行できません。 |
関連項目: このプロシージャの使用方法の詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください。 |
このプロシージャは、ソース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);
パラメータ
表82-15 CONVERTTOBLOBプロシージャのパラメータ
パラメータ | 説明 |
---|---|
|
宛先 |
|
ソース |
|
ソース
|
|
( |
|
( ( |
|
変換データの目的とするキャラクタ・セットID。 |
|
( ( この情報は、ユーザーがこの情報を使用してソース・データを失ったり、誤って解釈したりすることなく継続して変換できるようにするために戻されます。最初の変換の場合、または特に必要ない場合は、デフォルト値の0(ゼロ)を使用してください。 |
|
( 現在、発生する可能性があるのは、変換不可能な文字に関する警告のみです。これは、ソースの文字が宛先の文字に正しく変換できない場合に発生します。変換不可能な文字のかわりに、デフォルトの置換文字('?'など)が使用されます。このエラー・メッセージの戻り値は、 |
使用上の注意
事前条件
CONVERTTOBLOB
プロシージャをコールする前に、次の事前条件を満たしている必要があります。
ソースと宛先の両方のLOB
インスタンスが存在している。
宛先LOB
が永続LOB
の場合、行がロックされている。行をロックするには、SELECT
文のFOR
UPDATE
句を使用して、LOB
を選択します。
定数およびデフォルト
すべてのパラメータが必要です。各OUT
またはIN OUT
パラメータに変数を渡す必要があります。各IN
パラメータに変数または値を渡す必要があります。
表82-16に各パラメータの一般的な値の要約を示します。1列目にパラメータ、2列目に一般的な値を示し、最後の列は値を渡した結果を説明しています。値によっては定数が使用されるので注意してください。このような定数は、dbmslob.sql
パッケージ仕様部ファイルに定義されています。
表82-16 DBMS_LOB.CONVERTTOBLOBの一般的な値
パラメータ | 値 | 説明 |
---|---|---|
|
|
ファイル全体を変換します。 |
|
|
先頭から開始します。 |
|
|
先頭から開始します。 |
|
|
デフォルトの |
|
|
デフォルトの言語コンテキスト。 |
|
|
警告メッセージはありません。成功しました。 ソースの文字を正しく変換できません。 |
一般的な注意
blob_csid
パラメータに宛先LOB
の目的のキャラクタ・セットを指定する必要があります。blob_csid
には0(ゼロ)の値を渡せます。これを行う場合、データベースでは目的のキャラクタ・セットがソースLOB
キャラクタ・セットと同じであると想定されます。
ソースおよび宛先の両方のLOBに対するオフセット、およびソースLOB
からコピーする文字数を指定する必要があります。amount
およびsrc_offset
値は文字単位、dest_offset
はバイト単位です。LOB
全体を変換するには、amount
パラメータにLOBMAXSIZE
を指定します。
CONVERTTOBLOB
は、データの変換および書込み前に、必要に応じてソースまたは宛先LOB
(あるいはその両方)を取得します。
例外
表82-17に、このプロシージャがスローする可能性のある例外を示します。1列目は例外の文字列を示し、2列目は例外の原因となる可能性のあるエラー条件を説明しています。
表82-17 CONVERTTOBLOBプロシージャの例外
例外 | 説明 |
---|---|
|
入力パラメータのいずれかが |
|
次のいずれかの条件が発生しました。 - - - - |
関連項目: アプリケーション開発でのLOBの使用方法の詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください。 |
このプロシージャは、ソース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);
パラメータ
表82-18 CONVERTTOCLOBプロシージャのパラメータ
パラメータ | 説明 |
---|---|
|
宛先 |
|
ソース |
|
ソース BLOB全体をコピーする場合は、定数 |
|
|
|
( ( |
|
ソース・データのキャラクタ・セットID。 |
|
( この情報は、ユーザーがこの情報を使用してソース・データを失ったり、誤って解釈したりすることなく継続して変換できるようにするために戻されます。最初の変換の場合、または特に必要ない場合は、デフォルト値の0(ゼロ)を使用してください。 |
|
警告メッセージ。このパラメータは、変換時に何らかの異常が発生したことを示します。警告メッセージを確認する必要があります。 現在、発生する可能性があるのは、変換不可能な文字に関する警告のみです。これは、ソースの文字が宛先の文字に正しく変換できない場合に発生します。変換不可能な文字のかわりに、デフォルトの置換文字('?'など)が使用されます。このエラー・メッセージの戻り値は、 |
使用上の注意
事前条件
CONVERTTOCLOB
プロシージャをコールする前に、次の事前条件を満たしている必要があります。
ソースと宛先の両方のLOB
インスタンスが存在している。
宛先LOB
が永続LOB
の場合、CONVERTTOCLOB
プロシージャをコールする前に行がロックされている。行をロックするには、SELECT
文のFOR UPDATE
句を使用して、LOB
を選択します。
定数およびデフォルト
すべてのパラメータが必要です。各OUT
またはIN OUT
パラメータに変数を渡す必要があります。各IN
パラメータに変数または値を渡す必要があります。
表82-19に各パラメータの一般的な値の要約を示します。1列目にパラメータ、2列目に一般的な値を示し、最後の列は値を渡した結果を説明しています。値によっては定数が使用されるので注意してください。このような定数は、dbmslob.sql
パッケージ仕様部ファイルに定義されています。
表82-19 DBMS_LOB.CONVERTTOCLOBの一般的な値
パラメータ | 値 | 説明 |
---|---|---|
|
|
ファイル全体を変換します。 |
|
|
先頭から開始します。 |
|
|
先頭から開始します。 |
|
|
デフォルトの |
|
|
デフォルトの言語コンテキスト。 |
|
|
警告メッセージはありません。成功しました。 ソースの文字を正しく変換できません。 |
一般的な注意
blob_csid
パラメータに宛先LOB
の目的のキャラクタ・セットを指定する必要があります。blob_csid
には0(ゼロ)の値を渡せます。これを行う場合、データベースでは目的のキャラクタ・セットがソースLOB
キャラクタ・セットと同じであると想定されます。
ソースおよび宛先の両方のLOBに対するオフセット、およびソースLOB
からコピーする文字数を指定する必要があります。amount
およびsrc_offset
値は文字単位、dest_offset
はバイト単位です。LOB
全体を変換するには、amount
パラメータにLOBMAXSIZE
を指定します。
CONVERTTOCLOB
は、データの変換および書込み前に、必要に応じてソースまたは宛先LOB
(あるいはその両方)を取得します。
例外
表82-20 CONVERTTOCLOBプロシージャの例外
例外 | 説明 |
---|---|
|
入力パラメータのいずれかが |
|
次のいずれかの条件が発生しました。 - - - - |
関連項目: アプリケーション開発でのLOBの使用方法の詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください。 |
このプロシージャは、ソース内部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);
例外
表82-22 COPYプロシージャの例外
例外 | 説明 |
---|---|
|
入力パラメータのいずれかが |
|
次のいずれかです。 - - - - |
|
問合せまたはPDMLスレーブ内でLOB書込みを実行できません。 |
|
いずれかの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
は取り出されません。
関連項目: このプロシージャの使用方法の詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください。 |
このプロシージャは、ソース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);
このプロシージャは、アーカイブ・データをDBFSストアから読み取り、LOBに再度書き込みます。
このプロシージャは、一時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);
パラメータ
表82-27 CREATETEMPORARYプロシージャのパラメータ
パラメータ | 説明 |
---|---|
|
|
|
|
|
2つの事前定義の継続時間(
|
関連項目:
|
このサブプログラムは、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;
このプロシージャは、内部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);
パラメータ
表82-30 ERASEプロシージャのパラメータ
パラメータ | 説明 |
---|---|
|
消去する |
|
消去するバイト数( |
|
|
使用上の注意
LOB
の中央部のデータが消去されると、BLOB
またはCLOB
には、0(ゼロ)バイトのFILLERまたは空白がそれぞれ書き込まれます。
指定した数だけ消去する前にLOB
値の終わりに達した場合、実際に消去されたバイト数または文字数は、amount
パラメータで指定した数と異なる場合があります。実際に消去された文字数またはバイト数は、amount
パラメータに戻されます。
ERASE
は、アーカイブされているLOB
を取得します。ただし、消去がLOB
全体に適用される場合を除きます。
使用上の注意
オープン/クローズ・インタフェース内のLOB
操作のラップは必須ではありません。操作を実行する前にLOB
をオープンしなかった場合、LOB
列のファンクション索引およびドメイン索引は、コール中に更新されます。ただし、操作を実行する前にLOB
をオープンした場合は、トランザクションのコミットを実行する前にクローズする必要があります。内部LOB
がクローズされるときに、LOB
列のファンクション索引およびドメイン索引が更新されます。
オープン/クローズAPI内のLOB
操作をラップしなかった場合、ファンクション索引およびドメイン索引はLOB
へ書き込むたびに更新されます。これにより、パフォーマンスに悪影響を及ぼす可能性があります。したがって、LOB
への書込み操作をOPEN
またはCLOSE
文の中に囲むことをお薦めします。
このプロシージャは、入力ロケータによってすでにオープンされているBFILE
をクローズします。
注意: データベースには、BFILE に対する読取り専用アクセスしかありません。つまり、データベースを介してBFILE に書き込むことはできません。 |
例外
表82-33 FILECLOSEプロシージャの例外
例外 | 説明 |
---|---|
|
|
|
ファイルが入力ロケータを使用してオープンされていません。 |
|
ディレクトリが存在しません。 |
|
ディレクトリに対する権限がありません。 |
|
ディレクトリがファイルのオープン後に無効となりました。 |
|
ファイルが存在しないか、またはファイルのアクセス権限がありません。 |
関連項目:
|
このプロシージャは、セッションでオープンされたすべてのBFILE
をクローズします。
このファンクションは、指定したBFILE
ロケータが、サーバーのファイル・システムに実際に存在しているファイルを指しているかどうかを検証します。
このプロシージャは、指定したBFILE
ロケータのディレクトリ・オブジェクトとファイル名を判別します。ロケータに割り当てられたディレクトリ・オブジェクト名とファイル名を示すのみで、物理ファイルまたはディレクトリが実際に存在しているかどうかは判別しません。
dir_alias
バッファの最大値は30で、パス名全体の最大値は2000です。
このファンクションは、BFILE
が特定のFILE
ロケータでオープンされたかどうかを検証します。
使用上の注意
入力FILE
ロケータがFILEOPEN
プロシージャに渡されていない場合、そのファイルはこのロケータによってオープンされていないとみなされます。ただし、別のロケータがこのファイルをオープンしている可能性はあります。つまり、オープンされているかどうかは特定のロケータと関連付けられています。
このプロシージャは、BFILE
を読取り専用アクセスでオープンします。データベースを介してBFILE
に書き込むことはできません。
例外
表82-43 FILEOPENプロシージャの例外
例外 | 説明 |
---|---|
|
|
|
|
|
セッション内のオープン・ファイル数が |
|
|
|
ディレクトリがファイルのオープン後に無効となりました。 |
|
ファイルが存在しないか、またはファイルのアクセス権限がありません。 |
関連項目:
|
このプロシージャは、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);
パラメータ
表82-44 FRAGMENT_DELETEプロシージャのパラメータ
パラメータ | 説明 |
---|---|
|
LOBロケータ。詳細は、「使用上の注意」を参照してください。 |
|
LOBから削除するバイト数( |
|
削除を開始するLOB内のオフセット位置を示すバイト数( |
このプロシージャは、指定したデータ(最大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);
パラメータ
表82-46 FRAGMENT_INSERTプロシージャのパラメータ
パラメータ | 説明 |
---|---|
|
LOBロケータ。詳細は、「使用上の注意」を参照してください。 |
|
LOBに挿入するバイト数(BLOB)または文字数(CLOB/NCLOB)。 |
|
挿入を開始するLOB内のオフセット位置を示すバイト数(BLOB)または文字数(CLOB/NCLOB)。 |
|
LOBに挿入するデータ。 |
このプロシージャは、指定したオフセット位置から新しく指定したオフセット位置に、バイト単位(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);
パラメータ
表82-48 FRAGMENT_MOVEプロシージャのパラメータ
パラメータ | 説明 |
---|---|
|
LOBロケータ。詳細は、「使用上の注意」を参照してください。 |
|
|
|
データの挿入を開始する |
|
データの削除を開始する |
このプロシージャは、指定したオフセット位置にあるデータを指定したデータ(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);
パラメータ
表82-50 FRAGMENT_REPLACEファンクションのパラメータ
パラメータ | 説明 |
---|---|
|
LOBロケータ。詳細は、「使用上の注意」を参照してください。 |
|
|
|
LOBに書き込むバイト数( |
|
データの挿入を開始するLOB内のオフセット位置を示すバイト数(BLOB)または文字数( |
|
|
このプロシージャは、デフォルト一時表領域内の一時BLOB
またはCLOB
を解放します。
構文
DBMS_LOB.FREETEMPORARY ( lob_loc IN OUT NOCOPY BLOB); DBMS_LOB.FREETEMPORARY ( lob_loc IN OUT NOCOPY CLOB CHARACTER SET ANY_CS);
使用上の注意
新しい一時LOB
の作成時に、同じ継続時間(セッション、コール)で使用されている一時LOB
が存在しない場合は、新しい一時LOB
セグメントが作成されます。一時LOB
を解放すると、その一時LOBによって消費されていた領域が一時セグメントに解放されます。同じ継続時間が指定されているその他の一時LOB
が存在しない場合は、一時セグメントも解放されます。
FREETEMPORARY
へのコール後、解放されたLOB
ロケータには無効のマークが設定されます。
無効のLOB
ロケータが、OCIのOCILobLocatorAssign
を使用して、またはPL/SQLの割当て操作によって別のLOB
ロケータに割り当てられている場合、割当て先も解放され、無効のマークが設定されます。
関連項目: このプロシージャの使用方法の詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください。 |
このファンクションは指定したSecureFileに関連付けられた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);
このプロシージャは、指定したSecureFileの現在のDBFSリンク状態を取得します。
構文
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);
このプロシージャは、SETCONTENTTYPEプロシージャを使用して以前設定したコンテンツ・タイプ文字列を戻します。
このファンクションは、指定した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;
表の作成時に、チャンク・ファクタ(表領域ブロックのバイト単位の倍数)を指定できます。これは、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;
使用上の注意
基本的なLOBファイルの場合、このチャンク・サイズの倍数を使用して読取り/書込み要求を入力すると、パフォーマンスが向上します。LOB
チャンクはバージョン化され、すべての書込みがチャンクを基準に行われると、余分なバージョン分割が行われず、重複もしないため、書込みの場合にはさらに利点があります。同じチャンクに対してWRITE
コールを複数回発行するかわりに、1つのチャンク内でWRITE
コールを十分な数だけまとめることができます。
これらのパフォーマンスを向上させる方法は、SecureFilesには適用されません。
チャンク・サイズはLOBタイプ(BLOB
、CLOB
、NCLOB
、Unicodeまたはその他のキャラクタ・セット)とは無関係です。
関連項目: このプロシージャの使用方法の詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください。 |
このファンクションは、指定された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;
このファンクションは、特定のLOB
のoption_type
フィールドに対応する設定を取得します。
構文
DBMS_LOB.GETOPTIONS ( lob_loc IN BLOB, option_types IN PLS_INTEGER) RETURN PLS_INTEGER; DBMS_LOB.GETOPTIONS ( lob_loc IN CLOB HARACTER SET ANY_CS, option_types IN PLS_INTEGER) RETURN PLS_INTEGER;
パラメータ
表82-64 GETOPTIONSファンクションのパラメータ
パラメータ | 説明 |
---|---|
|
検査する |
|
「DBMS_LOBの定数: オプション・タイプ」を参照してください。 |
戻り値
戻り値は、渡されるオプション・タイプ(「DBMS_LOBの定数: オプション・タイプ」を参照)に応じて、COMPRESS_ON
、ENCRYPT_ON
およびDEDUPLICATE_ON
(「DBMS_LOBの定数: オプション値」を参照)の組合せになります。
使用上の注意
圧縮または複製解除の機能が備えられていないSecureFile列に対して、これらの機能をオンまたはオフにすることはできません。GetOptionsファンクションとSETOPTIONSプロシージャは、個々のSecureFilesに対して動作します。特定のSecureFileの機能をオフにしたり、SetOptionsによってすでにオフにされている機能をオンにすることはできますが、表の作成時にSecureFileに指定されていないオプションをオンにすることはできません。
このファンクションは、指定されたオフセットを開始位置として、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;
パラメータ
表82-66 INSTRファンクションのパラメータ
パラメータ | 説明 |
---|---|
|
検査する |
|
検査するLOBのファイル・ロケータ。 |
|
テスト対象のパターン。パターンは、 |
|
パターン・マッチングの開始位置を示す絶対オフセット(起点: 1)。 |
|
出現番号。1から始まります。 |
使用上の注意
VARCHAR2
バッファ(pattern
パラメータ)の形式は、CLOB
パラメータの形式と一致する必要があります。つまり、入力LOB
のパラメータのタイプがNCLOB
の場合、バッファにはNCHAR
データが含まれる必要があります。これに対して、入力LOB
のパラメータのタイプがCLOB
の場合、バッファにはCHAR
データが含まれる必要があります。
BFILE
の場合は、この操作を行う前に、FILEOPEN
操作でファイルをあらかじめオープンしておく必要があります。
INSTR
など、パターン・マッチング用にRAW
またはVARCHAR2
パラメータを受け入れる操作では、パターン・パラメータまたは副文字列において、正規表現または特殊一致文字(例: SQLのLIKE
)はサポートされていません。
例外
表82-68 BFILEに関するINSTRファンクションの例外
例外 | 説明 |
---|---|
|
ファイルが入力ロケータを使用してオープンされていません。 |
|
ディレクトリが存在しません。 |
|
ディレクトリに対する権限がありません。 |
|
ディレクトリがファイルのオープン後に無効となりました。 |
|
ファイルが存在しないか、またはファイルのアクセス権限がありません。 |
|
LOBでバッファが有効になっている場合、LOBバッファを有効にした状態では操作を実行できません。 |
このファンクションは、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;
使用上の注意
BFILES
の場合、オープンされているかどうかはロケータと関連付けられています。入力ロケータがOPEN
に渡されていない場合、そのBFILE
はこのロケータによってオープンされていないとみなされます。ただし、別のロケータがBFILE
をオープンしている可能性はあります。異なるロケータを使用すると、同じBFILE
上で複数のOPEN
を実行できます。
内部LOBの場合、オープンされているかどうかは、ロケータではなくそのLOB
に関連付けられています。ロケータ1がLOB
をオープンした場合、ロケータ2もそのLOB
はオープンしているとみなします。内部LOBの場合は、LOB
が実際にオープンしているかどうかを調べるにはサーバー上の状態をチェックするため、ISOPEN
でラウンドトリップが必要です。
外部LOB(BFILE
)の場合も、サーバーに状態が保持されているため、ISOPEN
でラウンドトリップが必要です。
関連項目: このプロシージャの使用方法の詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください。 |
このファンクションはLOB
インスタンスが一時的であるかどうかを判断します。
構文
DBMS_LOB.ISTEMPORARY ( lob_loc IN BLOB) RETURN INTEGER; DBMS_LOB.ISTEMPORARY ( lob_loc IN CLOB CHARACTER SET ANY_CS) RETURN INTEGER;
使用上の注意
FREETEMPORARY
を指定して一時LOBを解放した場合、LOBロケータはNULL
に設定されません。したがって、ISTEMPORARY
は、解放後に明示的にNULL
に再設定されていないロケータに対して0(ゼロ)を戻します。
関連項目: このプロシージャの使用方法の詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください。 |
このプロシージャは、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);
パラメータ
表82-71 LOADBLOBFROMFILEプロシージャのパラメータ
パラメータ | 説明 |
---|---|
|
ロード先の |
|
ロード元の |
|
|
|
( |
|
|
使用上の注意
ソースおよび宛先の両方の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
パラメータにデフォルト値を指定します。使用可能な定数およびデフォルトを次に示します。
表82-72 パラメータのデフォルト値
パラメータ | デフォルト値 | 説明 |
---|---|---|
|
|
ファイル全体をロードします。 |
|
|
先頭から開始します。 |
|
|
先頭から開始します。 |
DBMSLOB.SQL
で定義される定数
lobmaxsize CONSTANT INTEGER := DBMS_LOB.LOBMAXSIZE;
例外
表82-73 LOADBLOBFROMFILEプロシージャの例外
例外 | 説明 |
---|---|
|
入力パラメータのいずれかが |
|
次のいずれかです。 - - - - |
|
BLOBでバッファが有効になっている場合、LOBバッファを有効にした状態では操作を実行できません。 |
関連項目: このプロシージャの使用方法の詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください。 |
このプロシージャは、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);
パラメータ
表82-74 LOADCLOBFROMFILEプロシージャのパラメータ
パラメータ | 説明 |
---|---|
|
ロード先の |
|
ロード元の |
|
|
|
|
|
|
|
ソース( |
|
|
|
(OUT)警告メッセージ。これは、ロード時になんらかの異常が発生したことを示します。ユーザーのミスが原因の場合とそれ以外が原因の場合があります。ロードは要求に応じて完了され、警告メッセージをチェックするかどうかはユーザーが判断します。現在、発生する可能性があるのは、変換不可能な文字に関する警告のみです。これは、ソースの文字が宛先の文字に正しく変換できない場合に発生し、その位置にはデフォルトの置換文字(例: '?')が使用されます。メッセージは、定数値 |
使用上の注意
ソースおよび宛先の両方の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文字を一連のバイトにマッピングする複数のコード体系が定義されています。表82-75「サポートされているUnicodeコード体系」に、このサブプログラムでサポートされているUnicodeコード体系を示します。
表82-75 サポートされているUnicodeコード体系
コード体系 | Oracle名 | bfile_csid値 |
---|---|---|
|
|
873 |
|
|
2000 |
|
|
2002 |
|
|
871 |
|
|
872 |
|
|
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
にはロードされません。
表82-76 パラメータのデフォルト値
パラメータ | デフォルト値 | 説明 |
---|---|---|
|
|
ファイル全体をロードします。 |
|
|
先頭から開始します。 |
|
|
先頭から開始します。 |
|
|
デフォルトのcsid。宛先のcsidを使用します。 |
|
|
デフォルトの言語コンテキスト。 |
|
|
警告メッセージはありません。問題ありません。 |
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;
例外
表82-77 LOADCLOBFROMFILEプロシージャの例外
例外 | 説明 |
---|---|
|
入力パラメータのいずれかが |
|
次のいずれかです。 - - - - |
|
CLOBでバッファが有効になっている場合、LOBバッファを有効にした状態では操作を実行できません。 |
関連項目: このプロシージャの使用方法の詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください。 |
このプロシージャは、ソース外部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
の場合はバイト単位、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
文の中に囲むことをお薦めします。
このプロシージャは、指定したSecureFileデータをDBFSストアに書き込みます。
構文
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);
このプロシージャは、指定されたモードで、(内部または外部)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);
パラメータ
表82-82 OPENプロシージャのパラメータ
パラメータ | 説明 |
---|---|
|
LOBロケータ。詳細は、「使用上の注意」を参照してください。 |
|
オープンするモード。
|
使用上の注意
注意: LOB が読取り専用モードでオープンされた場合は、そのLOB に書込みを行おうとすると、エラーが戻されます。BFILE は、読取り専用モードでのみオープンできます。 |
OPEN
では、内部または外部LOBのいずれの場合もサーバーへのラウンドトリップが必要です。内部LOBの場合、OPEN
はOPEN
コールに依存しているその他のコードのトリガーとなります。外部LOB (BFILE
)の場合、OPEN
ではサーバー側の実際のオペレーティング・システム・ファイルがオープンされるため、ラウンドトリップが必要です。
オープン/クローズ・インタフェース内のすべてのLOB
操作のラップは必須ではありません。ただし、LOB
をオープンしている場合は、トランザクションのコミットを実行する前にクローズする必要があり、クローズしない場合は、エラーが発生します。内部LOB
がクローズされるときに、LOB
列のファンクション索引およびドメイン索引が更新されます。
トランザクションによってオープンされたすべてのLOBをクローズする前にトランザクションをコミットすると、エラーが発生します。エラーが戻された場合、LOBのオープンは廃棄されますが、トランザクションのコミットは正常に行われます。したがって、そのトランザクションにおけるLOB
および非LOBデータの変更はすべてコミットされますが、ドメイン索引およびファンクションベースの索引は更新されません。このような場合は、LOB
列のファンクション索引およびドメイン索引を再構築する必要があります。
関連項目: このプロシージャの使用方法の詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください。 |
このプロシージャは、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);
パラメータ
表82-83 READプロシージャのパラメータ
パラメータ | 説明 |
---|---|
|
読み込む |
|
検査する |
|
読み込む、または読み込まれたバイト数( |
|
|
|
読取り操作用の出力バッファ。 |
例外
表82-84に、すべてのLOB
インスタンスに該当する例外を示します。表82-85に、BFILE
のみに該当する例外を示します。
表82-84 READプロシージャの例外
例外 | 説明 |
---|---|
|
|
|
次のいずれかです。 - - - - - |
|
|
表82-85 BFILEに関するREADプロシージャの例外
例外 | 説明 |
---|---|
|
ファイルが入力ロケータを使用してオープンされていません。 |
|
ディレクトリが存在しません。 |
|
ディレクトリに対する権限がありません。 |
|
ディレクトリがファイルのオープン後に無効となりました。 |
|
ファイルが存在しないか、またはファイルのアクセス権限がありません。 |
|
LOBでバッファが有効になっている場合、LOBバッファを有効にした状態では操作を実行できません。 |
使用上の注意
VARCHAR2
バッファの形式は、CLOB
パラメータの形式と一致する必要があります。つまり、入力LOB
のパラメータのタイプがNCLOB
の場合、バッファにはNCHAR
データが含まれる必要があります。これに対して、入力LOB
のパラメータのタイプがCLOB
の場合、バッファにはCHAR
データが含まれる必要があります。
クライアントからDBMS_LOB
.READ
をコールすると(SQL*Plus内からのBEGIN
/END
ブロックでのコールなど)、戻されるバッファにはクライアントのキャラクタ・セットのデータが含まれます。データベースは、バッファをユーザーに戻す前に、サーバーのキャラクタ・セットからクライアントのキャラクタ・セットにLOB
値を変換します。
READは、読取り前に必要に応じてLOB
を取得します。
関連項目: このプロシージャの使用方法の詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください。 |
このファンクションは、指定した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));
パラメータ
表82-86 SET_DBFS_LINKプロシージャのパラメータ
パラメータ | 説明 |
---|---|
|
参照値を格納する |
|
いずれかのGET_DBFS_LINKファンクションをコールすると戻されるアーカイブID。 |
このプロシージャは、LOB内のデータのコンテンツ・タイプ文字列値を設定します。
このプロシージャは、LOB単位でCSCE機能を使用可能/使用禁止にして、デフォルトのLOB列設定より優先させます。
構文
DBMS_LOB.SETOPTIONS ( lob_loc IN BLOB, option_types IN PLS_INTEGER, options IN PLS_INTEGER); DBMS_LOB.SETOPTIONS ( lob_loc IN CLOB CHARACTER SET ANY_CS, option_types IN PLS_INTEGER, options IN PLS_INTEGER);
パラメータ
表82-90 SETOPTIONSプロシージャのパラメータ
パラメータ | 説明 |
---|---|
|
検査する |
|
「DBMS_LOBの定数: オプション・タイプ」を参照してください。 |
|
「DBMS_LOBの定数: オプション値」を参照してください。 |
使用上の注意
DBMS_LOB.SETOPTIONS
を使用して、個々のLOBに対する暗号化を使用可能または使用禁止にすることはできません。
圧縮または複製解除の機能が備えられていないSecureFile列に対して、これらの機能をオンまたはオフにすることはできません。GetOptionsファンクションとSetOptionsプロシージャは、個々のSecureFilesに対して動作します。特定のSecureFileの機能をオフにしたり、SetOptionsによってすでにオフにされている機能をオンにすることはできますが、表の作成時にSecureFileに指定されていないオプションをオンにすることはできません。
このファンクションは、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;
パラメータ
表82-92 SUBSTRファンクションのパラメータ
パラメータ | 説明 |
---|---|
|
読み込む |
|
検査する |
|
読み込むバイト数( |
|
|
例外
表82-94 BFILE操作に関するSUBSTRファンクションの例外
例外 | 説明 |
---|---|
|
ファイルが入力ロケータを使用してオープンされていません。 |
|
ディレクトリが存在しません。 |
|
ディレクトリに対する権限がありません。 |
|
ディレクトリがファイルのオープン後に無効となりました。 |
|
ファイルが存在しないか、またはファイルのアクセス権限がありません。 |
|
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
の値を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);
パラメータ
表82-95 TRIMプロシージャのパラメータ
パラメータ | 説明 |
---|---|
|
長さを切り捨てる内部 |
|
切り捨て後の新しい |
使用上の注意
オープン/クローズ・インタフェース内のLOB
操作のラップは必須ではありません。操作を実行する前にLOB
をオープンしなかった場合、LOB
列のファンクション索引およびドメイン索引は、コール中に更新されます。ただし、操作を実行する前にLOB
をオープンした場合は、トランザクションのコミットを実行する前にクローズする必要があります。内部LOB
がクローズされるときに、LOB
列のファンクション索引およびドメイン索引が更新されます。
オープン/クローズAPI内のLOB
操作をラップしなかった場合、ファンクション索引およびドメイン索引はLOB
へ書き込むたびに更新されます。これにより、パフォーマンスに悪影響を及ぼす可能性があります。したがって、LOB
への書込み操作をOPEN
またはCLOSE
文の中に囲むことをお薦めします。
TRIM
は、LOB
の長さを変更する前に、必要に応じてLOB
を取得します。ただし、指定する新しい長さが0(ゼロ)の場合を除きます。
関連項目:
|
このプロシージャは、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);
パラメータ
表82-97 WRITEプロシージャのパラメータ
パラメータ | 説明 |
---|---|
|
書込み先の内部 |
|
書き込むバイト数( |
|
|
|
書込み用の入力バッファ。 |
例外
表82-98 WRITEプロシージャの例外
例外 | 説明 |
---|---|
|
|
|
次のいずれかです。 - - - - |
|
問合せまたはPDMLスレーブ内でLOB書込みを実行できません。 |
|
LOBでバッファが有効になっている場合、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
全体を上書きするように指定されている場合を除きます。
関連項目:
|
このプロシージャは、指定された量のデータを内部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);
パラメータ
表82-99 WRITEAPPENDプロシージャのパラメータ
パラメータ | 説明 |
---|---|
|
書込み先の内部 |
|
書き込むバイト数( |
|
書込み用の入力バッファ。 |
使用上の注意
入力amountがバッファのデータより多い場合はエラーが発生します。入力amountがバッファのデータより少ない場合は、バッファからその量のバイト数または文字数のみ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
を取得します。
関連項目:
|