DBMS_LOB
パッケージは、BLOB
、CLOB
、NCLOB
、BFILE
および一時LOBを操作するサブプログラムを提供します。 DBMS_LOB
を使用すると、各LOBの特定の部分またはLOB全体に対するアクセスおよび操作ができます。
関連項目: 『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』 |
この章では、次の項目について説明します。
概要
セキュリティ・モデル
定数
データ型
ルールおよび制限
使用上の注意
例外
DBMS_LOB
では、BLOB
、CLOB
およびNCLOB
の読取りおよび変更ができます。BFILE
に対しては、読取り専用操作を実行できます。LOB
操作の大部分が、このパッケージによって提供されます。
このパッケージは、SYS
の下に作成する必要があります。このパッケージが提供する操作は、パッケージ所有者SYS
ではなく、現行のコール・ユーザーのもとで実行されます。
無名PL/SQLブロックからコールされたDBMS_LOB
サブプログラムは、カレント・ユーザーの権限を使用して実行されます。 ストアド・プロシージャからコールされたDBMS_LOB
サブプログラムは、そのストアド・プロシージャの所有者の権限を使用して実行されます。
ユーザーはプロシージャの作成時に、AUTHID
を設定して定義者の権限または実行者の権限のどちらを使用するのかを指示できます。次に例を示します。
CREATE PROCEDURE proc1 authid definer ...
または
CREATE PROCEDURE proc1 authid current_user ...
関連項目: AUTHID および権限の詳細は、『Oracle Database PL/SQL言語リファレンス』を参照してください。 |
DIRECTORY
機能を使用すると、BFILE
に安全にアクセスできます。この機能の詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』および『Oracle Database SQL言語リファレンス』のBFILENAME
ファンクションに関する項を参照してください。
一時LOB
に関係するセキュリティ・モデルについては「使用上の注意」を参照してください。
DBMS_LOB
では、次の定数が定義されます。
表69-1 DBMS_LOBの定数
定数 | 定義 |
---|---|
FILE_READONLY |
|
LOB_READONLY |
|
|
|
|
|
|
|
|
|
表69-2 DBMS_LOBのオプション・タイプ
定数 | 定義 |
---|---|
OPT_COMPRESS |
|
OPT_ENCRYPT |
|
|
|
表69-3 DBMS_LOBのオプション値
定数 | 定義 |
---|---|
COMPRESS_OFF |
|
COMPRESS_ON |
|
|
|
|
|
|
|
|
|
DBMS_LOB
パッケージでは、表69-4に示すデータ型が使用されます。
表69-4 DBMS_LOBで使用されるデータ型
型 | 説明 |
---|---|
|
ソースまたは宛先のバイナリ |
|
ソースまたは宛先の |
|
ソースまたは宛先の文字 |
|
ソースまたは宛先の文字バッファ( |
|
バッファまたは |
|
データベースの外部に格納されているラージ・バイナリ・オブジェクト。 |
DBMS_LOB
パッケージは特別な型を定義しません。
NCLOB
は、固定幅および可変幅のマルチバイト各国語キャラクタ・セットを格納するためのCLOB
です。
CLOB
用のDBMS_LOB
サブプログラムの仕様部にある句ANY_CS
を使用すると、CLOB
型でCLOB
またはNCLOB
ロケータ変数を入力として受け入れることができます。
このパッケージにあるサブプログラムの仕様部に適用される規則は次のとおりです。
BLOB
およびBFILE
を操作するサブプログラムのlength
、offset
およびamount
パラメータは、バイト単位で指定する必要があります。
CLOB
を操作するサブプログラムのlength
、offset
およびamount
パラメータは、文字単位で指定する必要があります。
パラメータ値の指定時に次の制限事項に従わなかった場合(またはパラメータ値を指定しなかった場合)は、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ブロック内でオープンされたファイルは、ブロックの正常終了または異常終了の前にクローズしてください。
データベースでサポートされているLOBの最大サイズは、LOB列が存在する表領域のブロック・サイズの232-1(4294967295)倍と等しくなります。これによって、最大LOBサイズの範囲は8TBから128TBまでとなります。
最大バッファ・サイズの32767バイトはmaxbufsize
によって表します。
すべてのDBMS_LOB
サブプログラムは、LOB
ロケータをベースにして動作します。 DBMS_LOB
サブプログラムを正常に実行するためには、データベース表領域または外部ファイル・システムにすでに存在しているLOB
を示す入力ロケータを用意する必要があります。 『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』の第1章も参照してください。
データベースでLOBを使用するには、最初にSQLデータ定義言語(DDL)を使用して、LOB
列が含まれる表を定義する必要があります。
表にLOB
列を定義した後、表に内部LOBを移入するには、SQLデータ操作言語(DML)を使用して、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
の新しいコピーを指します。これ以降、他のロケータは、変更操作が行われたロケータと同じデータは参照しません。このような状況の場合、永続LOBでディープ・コピーは行われません。これは、CRスナップショットおよびバージョン・ページによって、ユーザーは独自のバージョンのLOB
を簡単に参照できるためです。
必要な場合は、OCIのロケータへのポインタを使用し、ロケータへの複数のポインタが同じ一時LOB
ロケータを指すように設定することによって、擬似REF
構文を取得できます。PL/SQLでは、1つの一時LOB
に対して複数のロケータは使用しないでください。一時LOB
ロケータは、参照によって別のプロシージャに渡される可能性があります。
一時LOBは表スキーマと関連付けられていないため、行内および行外の一時LOBという概念はありません。ユーザーが一時LOB
インスタンスを作成すると、エンジンによってLOB
データへのロケータが作成され戻されます。 PL/SQLのDBMS_LOB
パッケージ、PRO*C、OCIおよびその他のプログラム・インタフェースは、このロケータを介して、永続LOBに対する操作と同様に一時LOBを操作します。
クライアント側の一時LOBはサポートされていません。一時LOBはすべてサーバーに常駐します。
一時LOBは、永続LOBがサポートしているEMPTY_BLOB
またはEMPTY_CLOB
ファンクションをサポートしません。 EMPTY_BLOB
ファンクションは、LOB
の初期化を指定しますが、データの移入は行いません。
一時LOB
インスタンスは、適切なFREETEMPORARY
またはOCIDurationEnd
文でOCIまたはDBMS_LOB
パッケージを使用したときのみ破棄できます。
一時LOB
インスタンスは、適切なOCIおよびDBMS_LOB
文を使用することによって、標準の永続内部LOBと同様にアクセスおよび変更できます。 一時LOB
を永続LOB
に変更するには、OCIまたはDBMS_LOB
のCOPY
コマンドを明示的に使用して、一時LOB
を永続LOB
にコピーする必要があります。
セキュリティは、LOB
ロケータを介して提供されます。一時LOB
は、その作成ユーザーのみ参照できます。ロケータは、あるユーザーのセッションから別のユーザーのセッションに渡すことはできません。あるセッションから別のセッションにロケータを渡しても、元のセッションの一時LOBにはアクセスできません。一時LOB
参照は、各ユーザー固有のセッションに限定されます。別の場所のロケータを使用するユーザーは、同じLOB
IDを持つ自分のセッション内でのみLOBにアクセスできます。ユーザーがこれを試行することはお薦めしませんが、試行した場合でも他のユーザーのデータに影響を与えることはありません。
データベースは、V$TEMPORARY_LOBS
と呼ばれるv$
ビューにセッションごとの一時LOBを記録します。この中には、セッションごとに存在している一時LOB数に関する情報が含まれています。 V$
ビューは、DBAが使用するためのものです。セッションから、データベースはどのユーザーがその一時LOBを所有しているかを判断できます。 V$TEMPORARY_LOBS
をDBA_SEGMENTS
と組み合せて使用すると、DBAは、セッションで一時LOB用に使用されている領域の量を把握できます。これらの表を使用すると、DBAは一時LOBが使用している一時領域の緊急クリーンアップを監視して指示できます。
一時LOBに固有の注意事項は次のとおりです。
DBMS_LOB
のすべてのファンクションは、入力パラメータのいずれかがNULL
の場合、NULL
を戻します。 LOB
ロケータがNULL
として入力されると、DBMS_LOB
のすべてのプロシージャで例外が発生します。
CLOB
に基づく操作では、パラメータ(CLOB
パラメータやVARCHAR2
のバッファやパターンなど)のキャラクタ・セットIDが一致しているかどうかは検証されません。この確認はユーザーが各自で行ってください。
データ記憶域リソースは、DBAが異なるテンポラリ表領域を作成して制御します。必要に応じて、DBAはユーザーごとに別々のテンポラリ表領域を定義できます。
関連項目: NOCOPY 構文の詳細は、『Oracle Database PL/SQL言語リファレンス』を参照してください。 |
表69-5 DBMS_LOBの例外
例外 | コード | 説明 |
---|---|---|
|
|
LOBに書き込むデータが多すぎます。LOBサイズは最大4GBです。 |
|
|
LOBバッファを有効にした状態では操作を実行できません。 |
|
|
引数は |
|
|
現行の操作に使用しているディレクトリは、それが初めてアクセスされたか、または前回のアクセス以降にDBAによって変更された場合は無効です。 |
|
ループ読取り操作用の |
|
|
|
ファイルに指定されているディレクトリが存在しません。 |
|
|
ユーザーに、そのディレクトリまたはファイルの操作に必要なアクセス権限がありません。 |
|
|
オープン・ファイル数が最大値に達しました。 |
|
|
ファイル操作に失敗しました。 |
|
|
問合せまたはPDMLスレーブ内でLOB書込みを実行できません。 |
|
|
|
|
|
|
|
|
|
|
|
LOBの終わりを超えて |
|
|
|
|
|
要求された操作の実行に使用するファイルがオープンされていません。 |
|
|
サブプログラムのパラメータの値が無効のため、PL/SQLエラーが発生しました。 |
表69-6 DBMS_LOBパッケージのサブプログラム
サブプログラム | 説明 |
---|---|
|
ソース |
|
オープンしている内部または外部 |
|
2つの |
|
ソース |
|
ソース |
|
ソース |
|
一時 |
|
|
|
ファイルをクローズします。 |
|
オープンしているファイルをすべてクローズします。 |
|
ファイルがサーバー上に存在しているかどうかをチェックします。 |
ディレクトリ・オブジェクト名およびファイル名を取得します。 |
|
|
入力 |
|
ファイルをオープンします。 |
|
LOBからの長さを指定した場合、指定したオフセット位置にあるデータを削除します。 |
|
指定したデータ(最大32K)を、LOB内の指定したオフセット位置に挿入します。 |
|
指定したオフセット位置から新しく指定したオフセット位置に、バイト単位(BLOB)または文字単位(CLOB/NCLOB)で移動します。 |
|
指定したオフセット位置にあるデータを指定したデータ(32k以下)で置き換えます。 |
|
デフォルト一時表領域にある一時 |
|
|
|
LOB値の長さを取得します。 |
|
特定のLOBの |
|
データベース構成のLOBの記憶域制限を戻します。 |
|
|
|
|
|
ロケータが一時 |
|
|
|
|
|
|
|
指定されたモードで |
|
指定されたオフセット以降の |
|
LOB単位でCSCE機能を使用可能にして、デフォルトのLOB列設定より優先させます。 |
|
指定されたオフセット以降の |
|
|
|
|
|
|
このプロシージャは、ソース内部LOB
の内容を宛先LOB
に追加します。ソースLOB
全体を追加します。
APPEND
プロシージャは2種類、オーバーロードされています。
構文
DBMS_LOB.APPEND ( dest_lob IN OUT NOCOPY BLOB, src_lob IN BLOB); DBMS_LOB.APPEND ( dest_lob IN OUT NOCOPY CLOB CHARACTER SET ANY_CS, src_lob IN CLOB CHARACTER SET dest_lob%CHARSET);
パラメータ
例外
表69-8 APPENDプロシージャの例外
例外 | 説明 |
---|---|
|
ソースまたは宛先 |
|
問合せまたはPDMLスレーブ内でLOB書込みを実行できません。 |
|
いずれかのLOBでバッファが有効になっている場合、LOBバッファを有効にした状態では操作を実行できません。 |
使用上の注意
オープン/クローズ・インタフェース内のLOB
操作のラップは必須ではありません。操作を実行する前にLOB
をオープンしなかった場合、LOB
列のファンクション索引およびドメイン索引は、コール中に更新されます。ただし、操作を実行する前にLOB
をオープンした場合は、トランザクションのコミットまたはロールバックを実行する前にクローズする必要があります。内部LOB
がクローズされるときに、LOB
列のファンクション索引およびドメイン索引が更新されます。
オープン/クローズAPI内のLOB
操作をラップしなかった場合、ファンクション索引およびドメイン索引はLOB
へ書き込むたびに更新されます。これにより、パフォーマンスに悪影響を及ぼす可能性があります。したがって、LOB
への書込み操作をOPEN
またはCLOSE
文の中に囲むことをお薦めします。
関連項目: このプロシージャの使用方法の詳細は、『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);
パラメータ
例外
BFILE
が存在していてもオープンしていない場合、エラーは戻されません。エラーは、LOB
がオープンしていない場合に戻されます。
使用上の注意
CLOSE
では、内部または外部LOBのいずれの場合もサーバーへのラウンドトリップが必要です。内部LOBの場合、CLOSE
はクローズ・コールに依存するその他のコードをトリガーし、外部LOB(BFILE
)の場合は、サーバー側のオペレーティング・システム・ファイルを実際にクローズします。
オープン/クローズ・インタフェース内のすべての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;
プラグマ
pragma restrict_references(COMPARE, WNDS, WNPS, RNDS, RNPS);
パラメータ
表69-10 COMPAREファンクションのパラメータ
パラメータ | 説明 |
---|---|
|
最初の比較対象のLOBロケータ。 |
|
2番目の比較対象のLOBロケータ。 |
|
比較するバイト数( |
|
1番目の |
|
2番目の |
戻り値
INTEGER
: 比較が正常に行われた場合は0(ゼロ)、それ以外の場合は0(ゼロ)以外の整数が戻されます。
次の場合にNULL
が戻されます。
amount
< 1
amount
> LOBMAXSIZE
offset_1
またはoffset_2
< 1
offset_1
またはoffset_2
> LOBMAXSIZE
使用上の注意
比較できるのは、同じデータ型のLOB(BLOB
型のLOB
と他のBLOB
、CLOB
とCLOB
、BFILE
とBFILE
)に限られます。BFILE
の場合は、この操作を行う前に、FILEOPEN
操作でファイルをあらかじめオープンしておく必要があります。
offset
およびamount
パラメータによって指定した範囲のデータがすべて完全に一致すると0(ゼロ)が戻されます。一致しない場合は0(ゼロ)以外のINTEGER
が戻されます。
固定幅のnバイトのCLOB
の場合は、COMPARE
に対する入力amountの指定が(DBMS_LOB
.LOBMAXSIZE
/n)を超えると、(DBMS_LOB
.LOBMAXSIZE
/n)またはMax(length(clob1), length(clob2))のサイズのうち、小さい方の範囲で文字を比較します。
例外
表69-11 BFILE操作に関するCOMPAREファンクションの例外
例外 | 説明 |
---|---|
|
ファイルが入力ロケータを使用してオープンされていません。 |
|
ディレクトリが存在しません。 |
|
ディレクトリに対する権限がありません。 |
|
ディレクトリがファイルのオープン後に無効となりました。 |
|
ファイルが存在しないか、またはファイルのアクセス権限がありません。 |
|
いずれかの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);
パラメータ
表69-12 CONVERTTOBLOBプロシージャのパラメータ
パラメータ | 説明 |
---|---|
|
宛先 |
|
ソース |
|
ソース
|
|
( ( |
|
( ( |
|
変換データの目的とするキャラクタ・セットID。 |
|
( ( この情報は、ユーザーがこの情報を使用してソース・データを失ったり、誤って解釈したりすることなく継続して変換できるようにするために戻されます。最初の変換の場合、または特に必要ない場合は、デフォルト値の0(ゼロ)を使用してください。 |
|
( 現在、発生する可能性があるのは、変換不可能な文字に関する警告のみです。これは、ソースの文字が宛先の文字に正しく変換できない場合に発生します。変換不可能な文字のかわりに、デフォルトの置換文字('?'など)が使用されます。 このエラー・メッセージの戻り値は、 |
使用上の注意
事前条件
CONVERTTOBLOB
プロシージャをコールする前に、次の事前条件を満たしている必要があります。
ソースと宛先の両方のLOB
インスタンスが存在している。
宛先LOB
が永続LOB
の場合、行がロックされている。行をロックするには、SELECT
文のFOR
UPDATE
句を使用して、LOB
を選択します。
定数およびデフォルト
すべてのパラメータが必要です。各OUT
またはIN OUT
パラメータに変数を渡す必要があります。各IN
パラメータに変数または値を渡す必要があります。
表69-13に各パラメータの一般的な値の要約を示します。1列目にパラメータ、2列目に一般的な値を示し、最後の列は値を渡した結果を説明しています。値によっては定数が使用されるので注意してください。このような定数は、dbmslob.sql
パッケージ仕様部ファイルに定義されています。
表69-13 DBMS_LOB.CONVERTTOBLOBの一般的な値
パラメータ | 値 | 説明 |
---|---|---|
|
|
ファイル全体を変換します。 |
|
|
先頭から開始します。 |
|
|
先頭から開始します。 |
|
|
デフォルトの |
|
|
デフォルトの言語コンテキスト。 |
|
|
警告メッセージはありません。成功しました。 ソースの文字を正しく変換できません。 |
一般的な注意
blob_csid
パラメータに宛先LOB
の目的のキャラクタ・セットを指定する必要があります。blob_csid
には0の値を渡せます。これを行う場合、データベースでは目的のキャラクタ・セットがソースLOB
キャラクタ・セットと同じであると想定されます。
ソースおよび宛先の両方のLOBに対するオフセット、およびソースLOB
からコピーする文字数を指定する必要があります。 amount
およびsrc_offset
値は文字単位、dest_offset
はバイト単位です。LOB
全体を変換するには、amount
パラメータにLOBMAXSIZE
を指定します。
例外
表69-14に、このプロシージャがスローする可能性のある例外を示します。1列目は例外の文字列を示し、2列目は例外の原因となる可能性のあるエラー条件を説明しています。
表69-14 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);
パラメータ
表69-15 CONVERTTOCLOBプロシージャのパラメータ
パラメータ | 説明 |
---|---|
|
宛先 |
|
ソース |
|
ソース BLOB全体をコピーする場合は、定数 |
|
( ( |
|
( ( |
|
ソース・データのキャラクタ・セットID。 |
|
( この情報は、ユーザーがこの情報を使用してソース・データを失ったり、誤って解釈したりすることなく継続して変換できるようにするために戻されます。最初の変換の場合、または特に必要ない場合は、デフォルト値の0(ゼロ)を使用してください。 |
|
警告メッセージ。このパラメータは、変換時に何らかの異常が発生したことを示します。警告メッセージを確認する必要があります。 現在、発生する可能性があるのは、変換不可能な文字に関する警告のみです。これは、ソースの文字が宛先の文字に正しく変換できない場合に発生します。変換不可能な文字のかわりに、デフォルトの置換文字('?'など)が使用されます。 このエラー・メッセージの戻り値は、 |
使用上の注意
事前条件
CONVERTTOCLOB
プロシージャをコールする前に、次の事前条件を満たしている必要があります。
ソースと宛先の両方のLOB
インスタンスが存在している。
宛先LOB
が永続LOB
の場合、CONVERTTOCLOB
プロシージャをコールする前に行がロックされている。行をロックするには、SELECT
文のFOR UPDATE
句を使用して、LOB
を選択します。
定数およびデフォルト
すべてのパラメータが必要です。各OUT
またはIN OUT
パラメータに変数を渡す必要があります。各IN
パラメータに変数または値を渡す必要があります。
表69-16に各パラメータの一般的な値の要約を示します。1列目にパラメータ、2列目に一般的な値を示し、最後の列は値を渡した結果を説明しています。値によっては定数が使用されるので注意してください。このような定数は、dbmslob.sql
パッケージ仕様部ファイルに定義されています。
表69-16 DBMS_LOB.CONVERTTOCLOBの一般的な値
パラメータ | 値 | 説明 |
---|---|---|
|
|
ファイル全体を変換します。 |
|
|
先頭から開始します。 |
|
|
先頭から開始します。 |
|
|
デフォルトの |
|
|
デフォルトの言語コンテキスト。 |
|
|
警告メッセージはありません。成功しました。 ソースの文字を正しく変換できません。 |
一般的な注意
blob_csid
パラメータで、ソース・データのキャラクタ・セットを指定する必要があります。blob_csid
には0の値を渡せます。これを行う場合、データベースではBLOB
内の文字データが宛先CLOBと同じキャラクタ・セットであると想定されます。
ソースおよび宛先の両方のLOBに対するオフセット、およびソースLOB
からコピーするバイト数を指定する必要があります。 amount
およびsrc_offset
値はバイト単位、dest_offset
は文字単位です。BLOB全体を変換するには、amount
パラメータにLOBMAXSIZE
を指定します。
例外
表69-17 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);
パラメータ
表69-18 COPYプロシージャのパラメータ
パラメータ | 説明 |
---|---|
|
コピー先の |
|
コピー元の |
|
コピーするバイト数( |
|
宛先 |
|
ソース |
例外
表69-19 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
文の中に囲むことをお薦めします。
関連項目: このプロシージャの使用方法の詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください。 |
このプロシージャは、一時BLOB
またはCLOB
およびそれに対応する索引をユーザーのデフォルト一時表領域に作成します。
構文
DBMS_LOB.CREATETEMPORARY ( lob_loc IN OUT NOCOPY BLOB, cache IN BOOLEAN, dur IN PLS_INTEGER := DBMS_LOB.SESSION); DBMS_LOB.CREATETEMPORARY ( lob_loc IN OUT NOCOPY CLOB CHARACTER SET ANY_CS, cache IN BOOLEAN, dur IN PLS_INTEGER := 10);
パラメータ
表69-20 CREATETEMPORARYプロシージャのパラメータ
パラメータ | 説明 |
---|---|
|
|
|
|
|
3つの事前定義の継続時間(
|
関連項目:
|
このプロシージャは、内部LOB
全体、または内部LOBの一部を消去します。
構文
DBMS_LOB.ERASE ( lob_loc IN OUT NOCOPY BLOB, amount IN OUT NOCOPY INTEGER, offset IN INTEGER := 1); DBMS_LOB.ERASE ( lob_loc IN OUT NOCOPY CLOB CHARACTER SET ANY_CS, amount IN OUT NOCOPY INTEGER, offset IN INTEGER := 1);
パラメータ
表69-21 ERASEプロシージャのパラメータ
パラメータ | 説明 |
---|---|
|
消去する |
|
消去するバイト数( |
|
|
使用上の注意
LOB
の中央部のデータが消去されると、BLOB
またはCLOB
には、0(ゼロ)バイトのFILLERまたは空白がそれぞれ書き込まれます。
指定した数だけ消去する前にLOB
値の終わりに達した場合、実際に消去されたバイト数または文字数は、amount
パラメータで指定した数と異なる場合があります。実際に消去された文字数またはバイト数は、amount
パラメータに戻されます。
例外
表69-22 ERASEプロシージャの例外
例外 | 説明 |
---|---|
|
入力パラメータのいずれかが |
|
次のいずれかです。 - - |
|
問合せまたはPDMLスレーブ内でLOB書込みを実行できません。 |
|
LOBでバッファが有効になっている場合、LOBバッファを有効にした状態では操作を実行できません。 |
使用上の注意
オープン/クローズ・インタフェース内のLOB
操作のラップは必須ではありません。操作を実行する前にLOB
をオープンしなかった場合、LOB
列のファンクション索引およびドメイン索引は、コール中に更新されます。ただし、操作を実行する前にLOB
をオープンした場合は、トランザクションのコミットまたはロールバックを実行する前にクローズする必要があります。内部LOB
がクローズされるときに、LOB
列のファンクション索引およびドメイン索引が更新されます。
オープン/クローズAPI内のLOB
操作をラップしなかった場合、ファンクション索引およびドメイン索引はLOB
へ書き込むたびに更新されます。これにより、パフォーマンスに悪影響を及ぼす可能性があります。したがって、LOB
への書込み操作をOPEN
またはCLOSE
文の中に囲むことをお薦めします。
このプロシージャは、入力ロケータによってすでにオープンされているBFILE
をクローズします。
注意: データベースには、BFILE に対する読取り専用アクセスしかありません。つまり、データベースを介してBFILE に書き込むことはできません。 |
構文
DBMS_LOB.FILECLOSE ( file_loc IN OUT NOCOPY BFILE);
パラメータ
例外
表69-24 FILECLOSEプロシージャの例外
例外 | 説明 |
---|---|
|
|
|
ファイルが入力ロケータを使用してオープンされていません。 |
|
ディレクトリが存在しません。 |
|
ディレクトリに対する権限がありません。 |
|
ディレクトリがファイルのオープン後に無効となりました。 |
|
ファイルが存在しないか、またはファイルのアクセス権限がありません。 |
関連項目:
|
このプロシージャは、セッションでオープンされたすべてのBFILE
をクローズします。
構文
DBMS_LOB.FILECLOSEALL;
例外
関連項目:
|
このファンクションは、指定したBFILE
ロケータが、サーバーのファイル・システムに実際に存在しているファイルを指しているかどうかを検証します。
構文
DBMS_LOB.FILEEXISTS ( file_loc IN BFILE) RETURN INTEGER;
プラグマ
pragma restrict_references(FILEEXISTS, WNDS, RNDS, WNPS, RNPS);
パラメータ
戻り値
例外
表69-28 FILEEXISTSファンクションの例外
例外 | 説明 |
---|---|
|
ディレクトリが存在しません。 |
|
ディレクトリに対する権限がありません。 |
|
ディレクトリがファイルのオープン後に無効となりました。 |
関連項目:
|
このプロシージャは、指定したBFILE
ロケータのディレクトリ・オブジェクトとファイル名を判別します。ロケータに割り当てられたディレクトリ・オブジェクト名とファイル名を示すのみで、物理ファイルまたはディレクトリが実際に存在しているかどうかは判別しません。
dir_alias
バッファの最大値は30で、パス名全体の最大値は2000です。
構文
DBMS_LOB.FILEGETNAME ( file_loc IN BFILE, dir_alias OUT VARCHAR2, filename OUT VARCHAR2);
パラメータ
表69-29 FILEGETNAMEプロシージャのパラメータ
パラメータ | 説明 |
---|---|
|
|
|
ディレクトリ・オブジェクト名 |
|
|
例外
表69-30 FILEGETNAMEプロシージャの例外
例外 | 説明 |
---|---|
|
入力パラメータのいずれかが |
|
|
関連項目: このプロシージャの使用方法の詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください。 |
このファンクションは、BFILE
が特定のFILE
ロケータでオープンされたかどうかを検証します。
構文
DBMS_LOB.FILEISOPEN ( file_loc IN BFILE) RETURN INTEGER;
プラグマ
PRAGMA RESTRICT_REFERENCES(fileisopen, WNDS, RNDS, WNPS, RNPS
);
パラメータ
戻り値
INTEGER
: 0 =ファイルはオープンされていません。1 =ファイルはオープンされています。
使用上の注意
入力FILE
ロケータがFILEOPEN
プロシージャに渡されていない場合、そのファイルはこのロケータによってオープンされていないとみなされます。ただし、別のロケータがこのファイルをオープンしている可能性はあります。つまり、オープンされているかどうかは特定のロケータと関連付けられています。
例外
表69-32 FILEISOPENファンクションの例外
例外 | 説明 |
---|---|
|
ディレクトリが存在しません。 |
|
ディレクトリに対する権限がありません。 |
|
ディレクトリがファイルのオープン後に無効となりました。 |
関連項目:
|
このプロシージャは、BFILE
を読取り専用アクセスでオープンします。データベースを介してBFILE
に書き込むことはできません。
構文
DBMS_LOB.FILEOPEN ( file_loc IN OUT NOCOPY BFILE, open_mode IN BINARY_INTEGER := file_readonly);
パラメータ
例外
表69-34 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);
パラメータ
表69-35 FRAGMENT_DELETEプロシージャのパラメータ
パラメータ | 説明 |
---|---|
|
LOBロケータ。詳細は、「使用上の注意」を参照してください。 |
|
LOBから削除するバイト数( |
|
削除を開始するLOB内のオフセット位置を示すバイト数( |
例外
表69-36 FRAGMENT_DELETEプロシージャの例外
例外 | 説明 |
---|---|
|
操作に対してサポートされていないオブジェクト・タイプ。 |
|
パラメータ値が無効でした。 |
|
問合せ時に操作を実行できません。 |
|
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);
パラメータ
表69-37 FRAGMENT_INSERTプロシージャのパラメータ
パラメータ | 説明 |
---|---|
|
LOBロケータ。詳細は、「使用上の注意」を参照してください。 |
|
LOBに挿入するバイト数(BLOB)または文字数(CLOB/NCLOB)。 |
|
挿入を開始するLOB内のオフセット位置を示すバイト数(BLOB)または文字数(CLOB/NCLOB)。 |
|
LOBに挿入するデータ。 |
例外
表69-38 FRAGMENT_INSERTプロシージャの例外
例外 | 説明 |
---|---|
|
操作に対してサポートされていないオブジェクト・タイプ。 |
|
パラメータ値が無効でした。 |
|
問合せ時に操作を実行できません。 |
|
LOBバッファを有効にした状態では操作を実行できません。 |
|
|
|
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);
パラメータ
表69-39 FRAGMENT_MOVEプロシージャのパラメータ
パラメータ | 説明 |
---|---|
|
LOBロケータ。詳細は、「使用上の注意」を参照してください。 |
|
|
|
データの挿入を開始する |
|
データの削除を開始する |
例外
表69-40 FRAGMENT_MOVEプロシージャの例外
例外 | 説明 |
---|---|
|
操作に対してサポートされていないオブジェクト・タイプ。 |
|
パラメータ値が無効でした。 |
|
問合せ時に操作を実行できません。 |
|
LOBバッファを有効にした状態では操作を実行できません。 |
|
|
|
LOBの終わりを超えて |
|
|
使用上の注意
すべてのオフセット位置は事前移動オフセット位置です。
LOBの終わりを2以上超えてオフセット位置を設定することはできません。
このプロシージャは、指定したオフセット位置にあるデータを指定したデータ(32k以下)で置き換えます。
構文
DBMS_LOB.FRAGMENT_REPLACE ( lob_loc IN OUT NOCOPY BLOB, old_amount IN INTEGER, new_amount IN INTEGER, offset IN INTEGER, buffer IN RAW); DBMS_LOB.FRAGMENT_REPLACE ( lob_loc IN OUT NOCOPY CLOB CHARACTER SET ANY_CS, old_amount IN INTEGER, new_amount IN INTEGER, offset IN INTEGER, buffer IN VARCHAR2 CHARACTER SET lob_loc%CHARSET);
パラメータ
表69-41 FRAGMENT_REPLACEプロシージャのパラメータ
パラメータ | 説明 |
---|---|
|
LOBロケータ。詳細は、「使用上の注意」を参照してください。 |
|
|
|
LOBに書き込むバイト数( |
|
データの挿入を開始するLOB内のオフセット位置を示すバイト数(BLOB)または文字数( |
|
|
例外
表69-42 FRAGMENT_REPLACEプロシージャの例外
例外 | 説明 |
---|---|
|
操作に対してサポートされていないオブジェクト・タイプ。 |
|
パラメータ値が無効でした。 |
|
問合せ時に操作を実行できません。 |
|
LOBバッファを有効にした状態では操作を実行できません。 |
|
|
|
LOBの終わりを超えて |
|
|
使用上の注意
このプロシージャを起動することは、オフセット位置の既存のバイト数/文字数を削除して、オフセット位置に新しいバイト数/文字数を挿入することと同様です。
このプロシージャは、デフォルト一時表領域内の一時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およびラージ・オブジェクト開発者ガイド』を参照してください。 |
このファンクションは、指定した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);
パラメータ
戻り値
このファンクションから戻される値は、指定したLOBロケータの最大許容サイズです。 BLOB
の場合、戻り値は、LOBが存在する表領域のブロック・サイズによって異なり、表領域のブロック・サイズの(232)-1(4294967295)倍として計算されます。 CLOB
/NCLOB
の場合、戻り値は、表領域のブロック・サイズの(232)-1(4294967295)倍をCLOB
/NCLOB
の文字幅で割った値になります。
使用上の注意
関連項目: LOB記憶域制限の詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください。 |
表の作成時に、チャンク・ファクタ(表領域ブロックのバイト単位の倍数)を指定できます。これは、LOB
値のアクセスまたは変更時にLOB
データ・レイヤーによって使用されるチャンク・サイズに対応します。チャンクの一部はシステム関連情報の格納に使用され、それ以外の部分にLOB
値が格納されます。
このファンクションは、LOB
値を格納するLOB
チャンクで使用される領域容量を戻します。
構文
DBMS_LOB.GETCHUNKSIZE ( lob_loc IN BLOB) RETURN INTEGER; DBMS_LOB.GETCHUNKSIZE ( lob_loc IN CLOB CHARACTER SET ANY_CS) RETURN INTEGER;
プラグマ
PRAGMA RESTRICT_REFERENCES(getchunksize, WNDS, RNDS, WNPS, RNPS);
パラメータ
戻り値
BLOB
の場合に戻される値はバイト単位です。CLOB
の場合に戻される値は文字単位です。
使用上の注意
基本的なLOBファイルの場合、このチャンク・サイズの倍数を使用して読取り/書込み要求を入力すると、パフォーマンスが向上します。LOB
チャンクはバージョン化されるため、書込みの場合にはさらに利点があります。すべての書込みがチャンクを基準に行われると、余分なバージョン分割が行われず、重複もしません。同じチャンクに対してWRITE
コールを複数回発行するかわりに、1つのチャンクのサイズ内でWRITE
コールを十分な数だけまとめることができます。
これらのパフォーマンスを向上させる方法は、SecureFilesには適用されません。
関連項目: このプロシージャの使用方法の詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください。 |
例外
表69-46 GETCHUNKSIZEプロシージャの例外
例外 | 説明 |
---|---|
|
LOBでバッファが有効になっている場合、LOBバッファを有効にした状態では操作を実行できません。 |
このファンクションは、指定されたLOB値の長さを取得します。長さは、バイト数または文字数で戻されます。
BFILE
の場合に戻される長さには、EOF
(存在している場合)が含まれます。以前に行ったERASE
またはWRITE
操作でLOB
に挿入された0(ゼロ)バイトまたは空白のFILLERも長さに含まれます。空の内部LOBの長さは0(ゼロ)です。
構文
DBMS_LOB.GETLENGTH ( lob_loc IN BLOB) RETURN INTEGER; DBMS_LOB.GETLENGTH ( lob_loc IN CLOB CHARACTER SET ANY_CS) RETURN INTEGER; DBMS_LOB.GETLENGTH ( file_loc IN BFILE) RETURN INTEGER;
プラグマ
pragma restrict_references(GETLENGTH, WNDS, WNPS, RNDS, RNPS);
パラメータ
戻り値
LOBの長さが、INTEGER
としてバイト数または文字数で戻されます。 入力LOBがNULL
の場合または入力lob_loc
がNULL
の場合は、NULL
が戻されます。BFILE
の場合は、次の場合にエラーが戻されます。
lob_loc
に必要なディレクトリ権限とオペレーティング・システム権限がない場合
オペレーティング・システム読込みエラーのために、lob_loc
を読み込むことができない場合
関連項目: このプロシージャの使用方法の詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください。 |
例外
このファンクションは、特定のLOBのoption_type
フィールドに対応する設定を取得します。
構文
DBMS_LOB.GETOPTIONS ( lob_loc IN BLOB, option_types IN PLS_INTEGER) RETURN PLS_INTEGER; DBMS_LOB.GETOPTIONS ( lob_loc IN CLOB HARACTER SET ANY_CS, option_types IN PLS_INTEGER) RETURN PLS_INTEGER;
パラメータ
表69-49 GETOPTIONSファンクションのパラメータ
パラメータ | 説明 |
---|---|
|
検査する |
|
「DBMS_LOBのオプション・タイプ」を参照してください。 |
戻り値
戻り値は、渡されるオプション・タイプ(「DBMS_LOBのオプション・タイプ」を参照)に応じて、COMPRESS_ON
、ENCRYPT_ON
およびDEDUPLICATE_ON
(「DBMS_LOBのオプション値」を参照)の組合せになります。
例外
表69-50 GETOPTIONSファンクションの例外
例外 | 説明 |
---|---|
|
操作に対してサポートされていないオブジェクト・タイプ。 |
|
パラメータ値が無効でした。 |
|
問合せ時に操作を実行できません。 |
|
LOBバッファを有効にした状態では操作を実行できません。 |
|
|
|
|
このファンクションは、指定されたオフセットを開始位置として、LOB
におけるパターンのn番目に一致した位置を戻します。
構文
DBMS_LOB.INSTR ( lob_loc IN BLOB, pattern IN RAW, offset IN INTEGER := 1, nth IN INTEGER := 1) RETURN INTEGER; DBMS_LOB.INSTR ( lob_loc IN CLOB CHARACTER SET ANY_CS, pattern IN VARCHAR2 CHARACTER SET lob_loc%CHARSET, offset IN INTEGER := 1, nth IN INTEGER := 1) RETURN INTEGER; DBMS_LOB.INSTR ( file_loc IN BFILE, pattern IN RAW, offset IN INTEGER := 1, nth IN INTEGER := 1) RETURN INTEGER;
プラグマ
pragma restrict_references(INSTR, WNDS, WNPS, RNDS, RNPS);
パラメータ
表69-51 INSTRファンクションのパラメータ
パラメータ | 説明 |
---|---|
|
検査する |
|
検査するLOBのファイル・ロケータ。 |
|
テスト対象のパターン。パターンは、 |
|
パターン・マッチングの開始位置を示す絶対オフセット(起点: 1)。 |
|
出現番号。1から始まります。 |
戻り値
表69-52 INSTRファンクションの戻り値
戻り値 | 説明 |
---|---|
INTEGER |
一致したパターンの先頭のオフセット。バイト数または文字数で示されます。 パターンが見つからない場合は0(ゼロ)が戻されます。 |
NULL |
次のいずれかです。 - - - - |
使用上の注意
VARCHAR2
バッファ(pattern
パラメータ)の形式は、CLOB
パラメータの形式と一致する必要があります。つまり、入力LOB
のパラメータの型がNCLOB
の場合、バッファにはNCHAR
データが含まれる必要があります。これに対して、入力LOB
のパラメータの型がCLOB
の場合、バッファにはCHAR
データが含まれる必要があります。
BFILE
の場合は、この操作を行う前に、FILEOPEN
操作でファイルをあらかじめオープンしておく必要があります。
INSTR
など、パターン・マッチング用にRAW
またはVARCHAR2
パラメータを受け入れる操作では、パターン・パラメータまたは副文字列において、正規表現または特殊一致文字(例: SQLのLIKE
)はサポートされていません。
例外
表69-53 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;
プラグマ
PRAGMA RESTRICT_REFERENCES(isopen, WNDS, RNDS, WNPS, RNPS);
パラメータ
戻り値
戻り値は、LOBがオープンしている場合は1、それ以外の場合は0(ゼロ)です。
使用上の注意
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;
プラグマ
PRAGMA RESTRICT_REFERENCES(istemporary, WNDS, RNDS, WNPS, RNPS);
パラメータ
戻り値
戻り値は、LOB
が一時的にオープンしている場合は1、それ以外の場合は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);
パラメータ
表69-56 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
文の中に囲むことをお薦めします。
定数およびデフォルト
パラメータを省略する簡単な方法はありません。IN/OUT
パラメータに変数を宣言するか、またはIN
パラメータにデフォルト値を指定します。使用可能な定数およびデフォルトを次に示します。
表69-57 パラメータのデフォルト値
パラメータ | デフォルト値 | 説明 |
---|---|---|
|
|
ファイル全体をロードします。 |
|
|
先頭から開始します。 |
|
|
先頭から開始します。 |
DBMSLOB.SQL
で定義される定数
lobmaxsize CONSTANT INTEGER := DBMS_LOB.LOBMAXSIZE;
例外
表69-58 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);
パラメータ
表69-59 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文字を一連のバイトにマッピングする複数のコード体系が定義されています。表69-60「サポートされているUnicodeコード体系」に、このサブプログラムでサポートされているUnicodeコード体系を示します。
表69-60 サポートされている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
にはロードされません。
定数
使用可能な定数およびデフォルト値を次に示します。
表69-61 パラメータのデフォルト値
パラメータ | デフォルト値 | 説明 |
---|---|---|
|
|
ファイル全体をロードします。 |
|
|
先頭から開始します。 |
|
|
先頭から開始します。 |
|
|
デフォルトの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;
例外
表69-62 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);
パラメータ
表69-63 LOADFROMFILEプロシージャのパラメータ
パラメータ | 説明 |
---|---|
|
ロード先の |
|
ロード元の |
|
|
|
宛先 |
|
ソース |
使用上の注意
ソースおよび宛先の両方のLOBに対するオフセット、およびソースBFILE
からコピーするバイト数を指定できます。 amount
およびsrc_offset
は、BFILE
を参照するためバイト単位です。dest_offset
は、BLOB
の場合はバイト単位、CLOB
の場合は文字単位です。
注意: 入力BFILE は、このプロシージャを使用する前にオープンしている必要があります。バイナリBFILE データがCLOB にロードされる場合、キャラクタ・セット変換は暗黙的には実行されません。BFILE データは、データベース内のCLOB と同じキャラクタ・セットであることが必要です。これを検証するためのエラー・チェックは実行されません。 |
宛先LOB
に指定したオフセットが、現在そのLOB
に格納されているデータの終わりを超えている場合は、宛先BLOB
またはCLOB
に、0(ゼロ)バイトのFILLERまたは空白がそれぞれ挿入されます。オフセットが宛先LOB
の現行の長さより小さい場合、既存のデータは上書きされます。
入力amountおよびoffsetを加算した値がBFILE
内のデータの長さを超えた場合はエラーが発生します。
注意: UTF-8のようにキャラクタ・セットの幅が変化する場合、LOB 値は固定幅形式のUCS2で格納されます。 したがって、DBMS_LOB.LOADFROMFILE を使用している場合、BFILEのデータはUTF-8キャラクタ・セットではなくUCS2キャラクタ・セットにする必要があります。 ただし、CLOBまたはNCLOBにデータをロードするには、LOADFROMFILE ではなくsql*loader を使用してください。sql*loader は、必要なキャラクタ・セット変換を提供します。 |
オープン/クローズ・インタフェース内のLOB
操作のラップは必須ではありません。操作を実行する前にLOB
をオープンしなかった場合、LOB
列のファンクション索引およびドメイン索引は、コール中に更新されます。ただし、操作を実行する前にLOB
をオープンした場合は、トランザクションのコミットまたはロールバックを実行する前にクローズする必要があります。内部LOB
がクローズされるときに、LOB
列のファンクション索引およびドメイン索引が更新されます。
オープン/クローズAPI内のLOB
操作をラップしなかった場合、ファンクション索引およびドメイン索引はLOB
へ書き込むたびに更新されます。これにより、パフォーマンスに悪影響を及ぼす可能性があります。したがって、LOB
への書込み操作をOPEN
またはCLOSE
文の中に囲むことをお薦めします。
例外
表69-64 LOADFROMFILEプロシージャの例外
例外 | 説明 |
---|---|
|
入力パラメータのいずれかが |
|
次のいずれかです。 - - - - |
関連項目: このプロシージャの使用方法の詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください。 |
このプロシージャは、指定されたモードで、(内部または外部)LOB
をオープンします。有効なモードは読取り専用と読取り/書込みです。
構文
DBMS_LOB.OPEN ( lob_loc IN OUT NOCOPY BLOB, open_mode IN BINARY_INTEGER); DBMS_LOB.OPEN ( lob_loc IN OUT NOCOPY CLOB CHARACTER SET ANY_CS, open_mode IN BINARY_INTEGER); DBMS_LOB.OPEN ( file_loc IN OUT NOCOPY BFILE, open_mode IN BINARY_INTEGER := file_readonly);
パラメータ
表69-65 OPENプロシージャのパラメータ
パラメータ | 説明 |
---|---|
|
LOBロケータ。詳細は、「使用上の注意」を参照してください。 |
|
オープンするモード。
|
使用上の注意
注意: LOB が読取り専用モードでオープンされた場合は、そのLOB に書込みを行おうとすると、エラーが戻されます。BFILE は、読取り専用モードでのみオープンできます。 |
OPEN
では、内部または外部LOBのいずれの場合もサーバーへのラウンドトリップが必要です。内部LOBの場合、OPEN
はOPEN
コールに依存しているその他のコードのトリガーとなります。外部LOB(BFILE
)の場合は、サーバー側の実際のオペレーティング・システム・ファイルがオープンされるため、ラウンドトリップが必要です。
オープン/クローズ・インタフェース内のすべての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);
パラメータ
表69-66 READプロシージャのパラメータ
パラメータ | 説明 |
---|---|
|
読み込む |
|
検査する |
|
読み込む、または読み込まれたバイト数( |
|
|
|
読取り操作用の出力バッファ。 |
例外
表69-67に、すべてのLOB
インスタンスに該当する例外を示します。表69-68に、BFILEのみに該当する例外を示します。
表69-67 READプロシージャの例外
例外 | 説明 |
---|---|
|
|
|
次のいずれかです。 - - - - - |
|
|
表69-68 BFILEに関するREADプロシージャの例外
例外 | 説明 |
---|---|
|
ファイルが入力ロケータを使用してオープンされていません。 |
|
ディレクトリが存在しません。 |
|
ディレクトリに対する権限がありません。 |
|
ディレクトリがファイルのオープン後に無効となりました。 |
|
ファイルが存在しないか、またはファイルのアクセス権限がありません。 |
|
LOBでバッファが有効になっている場合、LOBバッファを有効にした状態では操作を実行できません。 |
使用上の注意
VARCHAR2
バッファの形式は、CLOB
パラメータの形式と一致する必要があります。つまり、入力LOB
のパラメータの型がNCLOB
の場合、バッファにはNCHAR
データが含まれる必要があります。これに対して、入力LOB
のパラメータの型がCLOB
の場合、バッファにはCHAR
データが含まれる必要があります。
クライアントからDBMS_LOB
.READ
をコールすると(SQL*Plus内からのBEGIN
/END
ブロックでのコールなど)、戻されるバッファにはクライアントのキャラクタ・セットのデータが含まれます。データベースは、バッファをユーザーに戻す前に、サーバーのキャラクタ・セットからクライアントのキャラクタ・セットにLOB
値を変換します。
関連項目: このプロシージャの使用方法の詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください。 |
このプロシージャは、LOB単位でCSCE機能を使用可能/使用禁止にして、デフォルトのLOB列設定より優先させます。
構文
DBMS_LOB.SETOPTIONS ( lob_loc IN BLOB, option_types IN PLS_INTEGER, options IN PLS_INTEGER); DBMS_LOB.SETOPTIONS ( lob_loc IN CLOB CHARACTER SET ANY_CS, option_types IN PLS_INTEGER, options IN PLS_INTEGER);
パラメータ
表69-69 SETOPTIONSプロシージャのパラメータ
パラメータ | 説明 |
---|---|
|
検査する |
|
「DBMS_LOBのオプション・タイプ」を参照してください。 |
|
「DBMS_LOBのオプション値」を参照してください。 |
例外
表69-70 SETOPTIONSプロシージャの例外
例外 | 説明 |
---|---|
|
操作に対してサポートされていないオブジェクト・タイプ。 |
|
パラメータ値が無効でした。 |
|
問合せ時に操作を実行できません。 |
|
LOBバッファを有効にした状態では操作を実行できません。 |
|
|
使用上の注意
DBMS_LOB.SETOPTIONS
を使用して、個々のLOBに対する暗号化を使用可能または使用禁止にすることはできません。
このファンクションは、LOB
の先頭からの絶対offset
から開始し、LOB
のamount
バイトまたは文字を戻します。
固定幅のn
バイトのCLOB
の場合、SUBSTR
に対する入力amountが(32767/n
)を超えると、長さ(32767/n
)の文字バッファまたはCLOB
の長さのうち、いずれか小さい方が戻されます。可変幅キャラクタ・セットのCLOBの場合、n
はCLOBの文字に使用される最大バイト幅です。
構文
DBMS_LOB.SUBSTR ( lob_loc IN BLOB, amount IN INTEGER := 32767, offset IN INTEGER := 1) RETURN RAW; DBMS_LOB.SUBSTR ( lob_loc IN CLOB CHARACTER SET ANY_CS, amount IN INTEGER := 32767, offset IN INTEGER := 1) RETURN VARCHAR2 CHARACTER SET lob_loc%CHARSET; DBMS_LOB.SUBSTR ( file_loc IN BFILE, amount IN INTEGER := 32767, offset IN INTEGER := 1) RETURN RAW;
プラグマ
pragma restrict_references(SUBSTR, WNDS, WNPS, RNDS, RNPS);
パラメータ
表69-71 SUBSTRファンクションのパラメータ
パラメータ | 説明 |
---|---|
|
読み込む |
|
検査する |
|
読み込むバイト数( |
|
|
戻り値
表69-72 SUBSTRファンクションの戻り値
戻り値 | 説明 |
---|---|
|
ファンクション・オーバーロード。パラメータに |
|
|
|
次のいずれかです。 - 入力パラメータのいずれかが - - - - |
例外
表69-73 BFILE操作に関するSUBSTRファンクションの例外
例外 | 説明 |
---|---|
|
ファイルが入力ロケータを使用してオープンされていません。 |
|
ディレクトリが存在しません。 |
|
ディレクトリに対する権限がありません。 |
|
ディレクトリがファイルのオープン後に無効となりました。 |
|
ファイルが存在しないか、またはファイルのアクセス権限がありません。 |
|
LOBでバッファが有効になっている場合、LOBバッファを有効にした状態では操作を実行できません。 |
使用上の注意
VARCHAR2
バッファの形式は、CLOB
パラメータの形式と一致する必要があります。つまり、入力LOB
のパラメータの型がNCLOB
の場合、バッファにはNCHAR
データが含まれる必要があります。これに対して、入力LOB
のパラメータの型がCLOB
の場合、バッファにはCHAR
データが含まれる必要があります。
クライアントからDBMS_LOB
.SUBSTR
をコールすると(SQL*Plus内からのBEGIN
/END
ブロックでのコールなど)、戻されるバッファにはクライアントのキャラクタ・セットのデータが含まれます。データベースは、バッファをユーザーに戻す前に、サーバーのキャラクタ・セットからクライアントのキャラクタ・セットにLOB
値を変換します。
関連項目:
|
このプロシージャは、内部LOB
の値をnewlen
パラメータで指定された長さに切り捨てます。BLOB
の場合はバイト数、CLOB
の場合は文字数で長さを指定します。
注意: TRIM プロシージャは、LOB の長さをnewlen パラメータで指定された値に減らします。 |
空のLOB
に対してTRIM
を実行すると、何も処理は行われずエラーは戻されません。newlen
で指定した新しい長さがLOB
のサイズよりも大きい場合は、例外が発生します。
構文
DBMS_LOB.TRIM ( lob_loc IN OUT NOCOPY BLOB, newlen IN INTEGER); DBMS_LOB.TRIM ( lob_loc IN OUT NOCOPY CLOB CHARACTER SET ANY_CS, newlen IN INTEGER);
パラメータ
表69-74 TRIMプロシージャのパラメータ
パラメータ | 説明 |
---|---|
|
長さを切り捨てる内部 |
|
切り捨て後の新しい |
例外
表69-75 TRIMプロシージャの例外
例外 | 説明 |
---|---|
|
|
|
次のいずれかです。 - - |
|
問合せまたはPDMLスレーブ内でLOB書込みを実行できません。 |
|
LOBでバッファが有効になっている場合、LOBバッファを有効にした状態では操作を実行できません。 |
使用上の注意
オープン/クローズ・インタフェース内のLOB
操作のラップは必須ではありません。操作を実行する前にLOB
をオープンしなかった場合、LOB
列のファンクション索引およびドメイン索引は、コール中に更新されます。ただし、操作を実行する前にLOB
をオープンした場合は、トランザクションのコミットまたはロールバックを実行する前にクローズする必要があります。内部LOB
がクローズされるときに、LOB
列のファンクション索引およびドメイン索引が更新されます。
オープン/クローズAPI内のLOB
操作をラップしなかった場合、ファンクション索引およびドメイン索引はLOB
へ書き込むたびに更新されます。これにより、パフォーマンスに悪影響を及ぼす可能性があります。したがって、LOB
への書込み操作をOPEN
またはCLOSE
文の中に囲むことをお薦めします。
関連項目:
|
このプロシージャは、LOB
の先頭からの絶対オフセットから開始し、指定された量のデータを内部LOB
に書き込みます。データは、buffer
パラメータから書き込まれます。
WRITE
は、オフセット位置以降LOB
にすでに存在しているデータを、指定した長さだけ置換(上書き)します。
構文
DBMS_LOB.WRITE ( lob_loc IN OUT NOCOPY BLOB, amount IN INTEGER, offset IN INTEGER, buffer IN RAW); DBMS_LOB.WRITE ( lob_loc IN OUT NOCOPY CLOB CHARACTER SET ANY_CS, amount IN INTEGER, offset IN INTEGER, buffer IN VARCHAR2 CHARACTER SET lob_loc%CHARSET);
パラメータ
表69-76 WRITEプロシージャのパラメータ
パラメータ | 説明 |
---|---|
|
書込み先の内部 |
|
書き込むバイト数( |
|
|
|
書込み用の入力バッファ。 |
例外
表69-77 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
文の中に囲むことをお薦めします。
関連項目:
|
このプロシージャは、指定された量のデータを内部LOB
の後ろに書き込みます。データは、buffer
パラメータから書き込まれます。
構文
DBMS_LOB.WRITEAPPEND ( lob_loc IN OUT NOCOPY BLOB, amount IN INTEGER, buffer IN RAW); DBMS_LOB.WRITEAPPEND ( lob_loc IN OUT NOCOPY CLOB CHARACTER SET ANY_CS, amount IN INTEGER, buffer IN VARCHAR2 CHARACTER SET lob_loc%CHARSET);
パラメータ
表69-78 WRITEAPPENDプロシージャのパラメータ
パラメータ | 説明 |
---|---|
|
書込み先の内部 |
|
書き込むバイト数( |
|
書込み用の入力バッファ。 |
使用上の注意
入力amountがバッファのデータより多い場合はエラーが発生します。入力amountがバッファのデータより少ない場合は、バッファからその量のバイト数または文字数のみLOB
の後ろに書き込まれます。
例外
表69-79 WRITEAPPENDプロシージャの例外
例外 | 説明 |
---|---|
|
|
|
次のいずれかです。 - - |
|
問合せまたはPDMLスレーブ内でLOB書込みを実行できません。 |
|
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
文の中に囲むことをお薦めします。
関連項目:
|