97 DBMS_LOB
DBMS_LOB
パッケージは、BLOB
、CLOB
、NCLOB
、BFILE
および一時LOBs
を操作するサブプログラムを提供します。DBMS_LOB
を使用すると、LOBの特定の部分またはLOB全体に対するアクセスおよび操作ができます。
この章のトピックは、次のとおりです:
97.1 DBMS_LOBの概要
DBMS_LOB
では、BLOB
、CLOB
およびNCLOB
の読取りおよび変更ができ、BFILE
に対しては、読取り専用操作を実行できます。LOB操作の大部分が、このパッケージによって提供されます。
97.2 DBMS_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に関係するセキュリティ・モデルについては、「操作上のノート」を参照してください。
97.3 DBMS_LOBの定数
このトピックでは、DBMS_LOBパッケージで使用される定数について説明しています。
表97-1 DBMS_LOBの定数 - 基本
定数 | タイプ | 値 | 説明 |
---|---|---|---|
|
|
|
コール継続時間を含む |
|
|
|
指定した |
|
|
|
指定したLOBを読取り専用モードでオープンします。 |
|
|
|
指定したLOBを読取り/書取りモードでオープンします。 |
|
|
18446744073709551615 |
LOBの最大サイズ(バイト単位)。 |
|
|
|
セッション継続時間を含む |
表97-2 DBMS_LOBの定数: オプション・タイプ
定数 | 定義 | 値 | 説明 |
---|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
表97-3 DBMS_LOBの定数 - オプション値
定数 | 定義 | 値 | 説明 |
---|---|---|---|
|
|
|
SETOPTIONSプロシージャに対しては、圧縮をオフに設定します。GETOPTIONSファンクションに対しては、圧縮はオフになっています。 |
|
|
|
SETOPTIONSプロシージャに対しては、圧縮をオンに設定します。GETOPTIONSファンクションに対しては、圧縮はオンになっています。 |
|
|
|
SETOPTIONSプロシージャに対しては、重複除外をオフに設定します。GETOPTIONSファンクションに対しては、重複除外はオフになっています。 |
|
|
|
SETOPTIONSプロシージャに対しては、重複除外をオンに設定します。GETOPTIONSファンクションに対しては、重複除外はオンになっています。 |
|
|
|
GETOPTIONSファンクションに対しては、暗号化はオフになっています。 |
|
|
|
GETOPTIONSファンクションに対しては、暗号化はオンになっています。 |
表97-4 DBMS_LOBの定数 - DBFS状態値のタイプ
定数 | 定義 | 値 | 説明 |
---|---|---|---|
|
|
|
LOBはアーカイブされていません。 |
|
|
|
LOBはアーカイブされていますが、RDBMSに読み込まれています。 |
|
|
|
LOBは現在アーカイブされています。 |
表97-5 DBMS_LOBの定数 - DBFSキャッシュ・フラグ
定数 | 定義 | 値 | 説明 |
---|---|---|---|
|
|
1 |
LOBデータをアーカイブに書き込みますが、RDBMS内のデータはキャッシュされたバージョンとして保持します。 |
|
|
|
LOBデータをアーカイブに書き込み、RDBMSから削除します。 |
表97-6 DBMS_LOBの定数: その他
定数 | 定義 | 値 | 説明 |
---|---|---|---|
|
|
|
コンテンツ・タイプ文字列に使用できる最大バイト数 |
|
|
|
DBFSパス名の最大長 |
97.4 DBMS_LOBのデータ・タイプ
このトピックの表では、DBMS_LOBによって使用されるデータ・タイプを示します。
表97-7 DBMS_LOBで使用されるデータ・タイプ
タイプ | 説明 |
---|---|
|
ソースまたは宛先のバイナリLOB。 |
|
ソースまたは宛先の |
|
ソースまたは宛先の文字LOB( |
|
ソースまたは宛先の文字バッファ( |
|
バッファまたはLOBのサイズ、LOBへのオフセットまたはアクセス量を指定します。 |
|
データベースの外部に格納されているラージ・バイナリ・オブジェクト。 |
DBMS_LOB
パッケージは特別なタイプを定義しません。
NCLOB
は、固定幅および可変幅のマルチバイト各国語文字セットを格納するためのCLOB
です。
CLOB
用のDBMS_LOB
サブプログラムの仕様部にある句ANY_CS
を使用すると、CLOB
タイプでCLOB
またはNCLOB
ロケータ変数を入力として受け入れることができます。
97.5 DBMS_LOBの操作上のノート
すべてのDBMS_LOB
サブプログラムは、LOBロケータをベースにして動作します。DBMS_LOB
サブプログラムを正常に実行するためには、データベース表領域または外部ファイル・システムにすでに存在しているLOBを示す入力ロケータを用意する必要があります。
『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』の第1章も参照してください。
12.2リリース以降、リモート表からローカル変数に永続LOBロケータを選択できるようになりました。リモート列には、BLOB、CLOBまたはNCLOB型を使用できます。リモート表からBFILE
を選択することはできません。リモート表のLOB値を参照するLOB変数はリモート・ロケータと呼ばれます。
BFILE用のものを除くすべてのDBMS_LOB
APIで、リモートLOBロケータに対する操作が可能になり、サポートされるようになりました。2つのロケータを受け入れるAPIでは、両方のLOBが1つのデータベースに存在している必要があります。
参照:
データベースでLOBを使用するには、最初にSQLデータ定義言語(DDL)を使用して、LOB列が含まれる表を定義する必要があります。
-
内部LOB
-
外部LOB
-
一時LOB
内部LOB
表にLOB列を定義した後、表に内部LOBを移入するには、SQLデータ操作言語(DML)を使用して、LOB列のロケータを初期化するか、または移入します。
外部LOB
外部LOB(BFILE)がLOBロケータで示されるようにするには、次のことを実行する必要があります。
-
有効な既存の物理ディレクトリを示す
DIRECTORY
オブジェクトが定義済であること、およびデータベースに対する読取り権限を伴った物理ファイル(追加対象のLOB)が存在していることを確認する必要があります。オペレーティング・システムでパス名の大文字と小文字が区別される場合は、必ず正しい形式でディレクトリを指定してください。 -
追加する外部LOBの
DIRECTORY
オブジェクトとファイル名をBFILENAME
ファンクションに追加して、外部LOBのLOBロケータを作成する必要があります。
これらの作業が終了すると、指定されたLOBロケータを使用して、LOB列が含まれている行を挿入または更新できます。
LOBの定義および作成が終了すると、SELECT
を実行してLOBロケータをローカルのPL/SQL LOB変数に割り当て、この変数をDBMS_LOB
の入力パラメータとして使用してLOB値にアクセスできます。
これを行うための別の方法の詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください。
一時LOB
データベースでは、一時LOBの定義、作成、削除、アクセスおよび更新がサポートされています。一時LOBデータは、ユーザーの一時表領域に格納されています。一時LOBはデータベースに永続的には格納されません。この目的は、主にLOBデータの変換の実行です。
一時LOBの場合は、OCI、PL/SQLまたはその他のプログラム・インタフェースを使用して作成または操作する必要があります。一時LOBは、BLOB
、CLOB
またはNCLOB
のいずれにもできます。
一時LOBは、作成されたときは空の状態です。デフォルトでは一時LOBは、それが作成されたセッションの終了時にすべて削除されます。処理が途中で停止したり、データベースがクラッシュした場合、一時LOBは削除され、その領域は解放されます。
一時LOBを論理バケットにまとめてグループ化するインタフェースもあります。一時LOB用のこの論理記憶域は期間で表されます。各一時LOBには、CACHE
やNOCACHE
など、別々の記憶特性があります。セッションごとにデフォルトの記憶域があり、ユーザーが特定の期間を指定しない場合、一時LOBはこの記憶域に格納されます。さらに、期間ごとに解放操作を実行して、期間内のすべてのコンテンツを解放できます。
一時LOBに関する、読込み一貫性(CR)、取消し、バックアップ、パラレル処理またはトランザクション管理はサポートされていません。一時LOBには、CRおよびロールバックがサポートされていないため、エラーが発生した場合、ユーザーは一時LOBを解放して、最初から操作をやりなおす必要があります。
CR、取消しおよびバージョンが、一時LOBに対しては生成されないため、同じ一時LOBに複数のロケータを割り当てると、パフォーマンスに影響する可能性があります。具体的には、各ロケータが一時LOBの独自のコピーを所有するためです。
別のロケータが一時LOBを指しているときにユーザーがその内容を変更する場合、一時LOBのコピーが作成されます。すると、変更が実行されたロケータは、一時LOBの新しいコピーをポイントするようになります。変更が行われたロケータと同様、他のロケータもそれ以降同じデータを参照しなくなります。このような状況では、CRスナップショットおよびバージョン・ページによって、ユーザーは独自のバージョンのLOBを簡単に参照できるため、永続LOBではディープ・コピーは生成されません。
必要な場合は、OCIのロケータへのポインタを使用し、ロケータへの複数のポインタが同じ一時LOBロケータを指すように設定することによって、擬似REF
構文を取得できます。PL/SQLでは、1つの一時LOBに対して複数のロケータは使用しないでください。一時LOBロケータは、参照によって別のプロシージャに渡される可能性があります。
一時LOBは表スキーマと関連付けられていないため、行内および行外の一時LOBという概念はありません。ユーザーが一時LOBインスタンスを作成すると、エンジンによってLOBデータへのロケータが作成され戻されます。PL/SQLのDBMS_LOB
パッケージ、PRO*C/C++、OCIおよびその他のプログラム・インタフェースは、このロケータを介して、永続LOBに対する操作と同様に一時LOBを操作します。
クライアント側の一時LOBはサポートされていません。一時LOBはすべてサーバーに常駐します。
一時LOBは、永続LOBがサポートしているEMPTY_BLOB
またはEMPTY_CLOB
ファンクションをサポートしません。EMPTY_BLOB
ファンクションは、LOBの初期化を指定しますが、データの移入は行いません。
一時LOBインスタンスは、適切なFREETEMPORARY
またはOCIDurationEnd
文でOCIまたはDBMS_LOB
パッケージを使用したときのみ破棄できます。
一時LOBインスタンスは、適切なOCIおよびDBMS_LOB
文を使用することによって、標準の永続内部LOBと同様にアクセスおよび変更できます。一時LOBを永続LOBにするには、OCIまたはDBMS_LOB
のCOPY
コマンドを明示的に使用して、一時LOBを永続LOBにコピーする必要があります。
セキュリティは、LOBロケータを介して提供されます。一時LOBは、その作成ユーザーのみ参照できます。ロケータは、あるユーザーのセッションから別のユーザーのセッションに渡すことはできません。あるセッションから別のセッションにロケータを渡しても、元のセッションの一時LOBにはアクセスできません。一時LOB参照は、各ユーザー固有のセッションに限定されます。別の場所のロケータを使用するユーザーは、同じLOBIDを持つ自分のセッション内でのみLOBにアクセスできます。ユーザーがこれを試行することはお薦めしませんが、試行した場合でも他のユーザーのデータに影響を与えることはありません。
データベースは、V$TEMPORARY_LOBS
と呼ばれるv$
ビューにセッションごとの一時LOBを記録しますが、このビューには、セッションごとに存在している一時LOB数に関する情報が含まれています。V$
ビューは、DBAが使用するためのものです。セッションから、データベースはどのユーザーが一時LOBを所有しているかを判断できます。V$TEMPORARY_LOBS
をDBA_SEGMENTS
と組み合せて使用することで、DBAは、セッションで一時LOB用に使用されている領域の量を把握できます。これらの表を使用すると、DBAは一時LOBが使用している一時領域の緊急クリーンアップを監視して指示できます。
一時LOBに固有のノートは次のとおりです。
-
DBMS_LOB
のすべてのファンクションは、入力パラメータのいずれかがNULL
の場合、NULL
を戻します。LOBロケータがNULL
として入力されると、DBMS_LOB
のすべてのプロシージャで例外が発生します。 -
CLOB
に基づく操作では、パラメータ(CLOB
パラメータやVARCHAR2
のバッファとパターンなど)の文字セットIDが一致しているかどうかは検証されません。この確認はユーザーが各自で行ってください。 -
データ記憶域リソースは、DBAが異なるテンポラリ表領域を作成して制御します。必要に応じて、DBAはユーザーごとに別々のテンポラリ表領域を定義できます。
参照:
NOCOPY
構文の詳細は、『Oracle Database PL/SQL言語リファレンス』を参照してください。
97.6 DBMS_LOBのルールおよび制限
このトピックでは、一般的なDBMS_LOBルールおよび制限、外部ファイル(BFILE)に固有のルールおよび制限、最大のLOBおよびバッファ・サイズを示します。
一般的なルールおよび制限
-
Oracle Databaseでは、LOBタイプの列または属性に対する制約はサポートされていませんが、例外としてLOBの列または属性に対する
NOT NULL
制約はサポートされています。 -
このパッケージにあるサブプログラムの仕様部に適用される規則は次のとおりです。
-
BLOB
およびBFILE
を操作するサブプログラムのnewlen
、offset
およびamount
パラメータは、バイト単位で指定する必要があります。 -
CLOB
を操作するサブプログラムのnewlen
、offset
およびamount
パラメータは、文字単位で指定する必要があります。
マルチバイトの文字セットでは、これらのオフセットを正しく解釈できません。結果として、
SUBSTR
では、ORA-22998: CLOB or NCLOB in multibyte character set not supported
というエラーが発生します。 -
-
パラメータ値の指定時に次の制限事項に従わなかった場合(またはパラメータ値を指定しなかった場合)は、
INVALID_ARGVAL
例外が発生します。-
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を含んだ行のロックは暗黙的には行われません。
外部ファイル(BFILE)に固有のルールと制限
-
サブプログラム
COMPARE
、INSTR
、READ
、SUBSTR
、FILECLOSE
、FILECLOSEALL
およびLOADFROMFILE
は、オープン済のBFILE
ロケータでのみ動作しますが、つまり、これらのサブプログラムのコール前にFILEOPEN
コールが正常に完了している必要があります。 -
ファンクション
FILEEXISTS
、FILEGETNAME
およびGETLENGTH
に関しては、ファイルのオープン/クローズ状態はあまり重要ではありません。ただし、ファイルが物理的に必ず存在し、ユーザーにDIRECTORY
オブジェクトとそのファイルに関する適切な権限があることが必要です。 -
DBMS_LOB
は、BFILE
操作に対する並行性制御メカニズムをサポートしません。 -
クローズ処理が正しく行われていない複数のオープン・ファイルがセッションで使用されている場合は、
FILECLOSEALL
サブプログラムを使用してセッションでオープンされたファイルをすべてクローズし、ファイル操作を最初からやり直すことができます。 -
DIRECTORY
の作成者である場合、またはシステム権限がある場合、SQLのCREATE
OR
REPLACE
、DROP
およびREVOKE
文の使用には特に注意してください。ユーザーまたは特定のディレクトリ・オブジェクトの権限受領者がセッション内に複数のファイルをオープンしている場合は、前述のコマンドが誤ってファイル操作に影響を与える場合があります。この状況で異常終了した場合は、必ず
FILECLOSEALL
をコールするプログラムまたは無名ブロックを起動し、ファイルを再オープンしてファイル操作を再開してください。 -
ユーザー・セッションの間にオープンされたファイルはすべて、セッション終了時に暗黙的にクローズされます。ただし、
BFILE
の操作の正常終了および異常終了いずれの場合も、操作終了後にファイルをクローズすることをお薦めします。プログラムが正常に終了した場合、ファイルを適切にクローズすることによって、セッションで同時にオープンしているファイル数は、必ず
SESSION_MAX_OPEN_FILES
より少なくなります。PL/SQLプログラムが異常終了した場合は、そのPL/SQLプログラム内でオープン中のすべてのファイルをクローズする例外ハンドラを使用する必要があります。例外が発生すると、最新の状態の
BFILE
変数にアクセスできるのは例外ハンドラのみであるため、この処理が必要です。例外によってプログラム制御がPL/SQLプログラム・ブロック外に転送されると、オープン中の
BFILE
への参照はすべて失われます。この結果、オープン・ファイル・カウントが増加し、SESSION_MAX_OPEN_FILES
値を超える場合があります。たとえば、
BFILE
値の終了位置を超えてREAD
操作を行い、NO_DATA_FOUND
例外が発生したと想定します。-- This assumes a directory 'DDD' whose path is already known DECLARE fil BFILE:= bfilename('DDD', 'filename.foo'); pos INTEGER; amt BINARY_INTEGER; buf RAW(40); BEGIN SELECT ad_graphic INTO fil FROM print_media WHERE product_id = 3106; dbms_lob.open(fil, dbms_lob.lob_readonly); amt := 40; pos := 1 + dbms_lob.getlength(fil); buf := ''; dbms_lob.read(fil, amt, pos, buf); dbms_output.put_line('Read F1 past EOF: '|| utl_raw.cast_to_varchar2(buf)); dbms_lob.close(fil); END; ORA-01403: no data found ORA-06512: at "SYS.DBMS_LOB", line 373 ORA-06512: at line 10
例外が発生した後、
BFILE
ロケータの変数ファイルは有効範囲外となり、その変数を使用したファイル操作は実行できなくなります。したがって、解決方法として、次のような例外ハンドラを使用します。DECLARE fil BFILE; pos INTEGER; amt BINARY_INTEGER; buf RAW(40); BEGIN SELECT ad_graphic INTO fil FROM print_media WHERE product_id = 3106; dbms_lob.open(fil, dbms_lob.lob_readonly); amt := 40; pos := 1 + dbms_lob.getlength(fil); buf := ''; dbms_lob.read(fil, amt, pos, buf); dbms_output.put_line('Read F1 past EOF: '|| utl_raw.cast_to_varchar2(buf)); dbms_lob.close(fil); exception WHEN no_data_found THEN BEGIN dbms_output.put_line('End of File reached. Closing file'); dbms_lob.fileclose(fil); -- or dbms_lob.filecloseall if appropriate END; END; / Statement processed. End of File reached. Closing file
通常、DBMS_LOB
を使用してPL/SQLブロック内でオープンされたファイルは、ブロックの正常終了または異常終了の前にクローズしてください。
最大LOBサイズ
データベースでサポートされているLOBの最大サイズは、LOB列が存在する表領域のブロック・サイズの232-1(4294967295)倍と等しくなります。これによって、最大LOBサイズの範囲は8TBから128TBまでとなります。
最大バッファ・サイズ
最大バッファ・サイズは32767バイトです。
バッファ・サイズをバイトで表現するBLOB
では、バイト数の上限は32767です。
バッファ・サイズを文字で表現するCLOB
またはNCLOB
では、文字数によるバッファの上限は32767バイトです。たとえば、固定幅の2バイト文字を使用する場合、(20000*2 = 40000は32767より大きいため)20000文字はエラーになります。
97.7 DBMS_LOBの例外
このトピックの表では、DBMS_LOBの例外を示します。
表97-8 DBMS_LOBの例外
例外 | コード | 説明 |
---|---|---|
|
|
LOBに書き込むデータが多すぎます。LOBサイズは最大4GBです。 |
|
|
|
|
|
|
|
|
引数は |
|
|
現行の操作に使用しているディレクトリは、それが初めてアクセスされたか、または前回のアクセス以降にDBAによって変更された場合は無効です。 |
|
|
ループ読取り操作用の |
|
|
ファイルに指定されているディレクトリが存在しません。 |
|
|
ユーザーに、そのディレクトリまたはファイルの操作に必要なアクセス権限がありません。 |
|
|
オープン・ファイル数が最大値に達しました。 |
|
|
ファイル操作に失敗しました。 |
|
|
問合せまたはPDMLパラレル実行サーバー内でLOB書込みが実行できません。 |
|
|
|
|
|
|
|
|
|
|
|
LOBの終わりを超えて |
|
|
要求された操作の実行に使用するファイルがオープンされていません。 |
|
|
サブプログラムのパラメータの値が無効のため、PL/SQLエラーが発生しました。 |
97.8 DBMS_LOBサブプログラムの要約
この表は、DBMS_LOB
サブプログラムを示し、簡単に説明しています。
表97-9 DBMS_LOBパッケージのサブプログラム
サブプログラム | 説明 |
---|---|
ソースLOBのコンテンツを宛先LOBに追加します。 |
|
|
|
オープンしている内部または外部LOBをクローズします。 |
|
2つの |
|
ソース |
|
ソース |
|
ソースLOBの全体または一部を宛先LOBにコピーします。 |
|
ソースLOBのDBFSリンクを宛先LOBにコピーします。 |
|
LOBのデータをDBFSストアから取得します。 |
|
一時 |
|
DBFSリンクの作成に使用する一意のファイル・パス名を戻します。 |
|
LOBの全体または一部を消去します。 |
|
ファイルをクローズします。 |
|
オープンしていたすべてのファイルをクローズします。 |
|
ファイルがサーバー上に存在するかどうかを確認します。 |
|
ディレクトリ・オブジェクト名とファイル名を取得します。 |
|
入力 |
|
ファイルをオープンします。 |
|
LOBからの長さを指定した場合、指定したオフセット位置にあるデータを削除します。 |
|
指定したデータ(最大32K)を、LOB内の指定したオフセット位置に挿入します。 |
|
指定したオフセット位置から新しく指定したオフセット位置に、バイト単位( |
|
指定したオフセット位置にあるデータを指定したデータ(32k以下)で置き換えます。 |
|
デフォルト一時表領域にある一時 |
|
指定したSecureFileに関連付けられたDBFSリンク・パスを戻します。 |
|
指定したSecureFileの現在のDBFSリンク状態を取得します。 |
|
LOB値を格納するLOBチャンクの使用領域容量を戻します。 |
|
SETCONTENTTYPEプロシージャを使用して以前設定したコンテンツID文字列を戻します。 |
|
LOB値の長さを取得します。 |
|
特定のLOBの |
|
データベース構成のLOBの記憶域制限を戻します。 |
|
LOBにあるパターンのn番目の一致のマッチング位置を戻します。 |
|
LOBが入力ロケータを使用して、すでにオープンされたかどうかをチェックします。 |
|
LOBがデータベースに対してローカルであるか、またはリモート・データベースに属しているかを確認します。 |
|
渡されるLOBロケータがSecurefiles LOB用の場合に |
|
ロケータが一時LOBをポイントしているかどうかをチェックします。 |
|
|
|
|
|
指定したSecureFileデータをDBFSストアに書き込みます。 |
|
指定されたモードでLOB(内部、外部またはテンポラリ)をオープンします。 |
|
指定されたオフセット以降のLOBデータを読み込みます。 |
|
指定したSecureFileを指定したパス名にリンクします。データはパスにコピーされません。 |
|
LOB内のデータのコンテンツ・タイプ文字列値を設定します。 |
|
LOB単位でCSCE機能を使用可能にして、デフォルトのLOB列設定より優先させます。 |
|
指定されたオフセット以降のLOB値の一部を戻します。 |
|
指定された長さまでLOB値を切り捨てます。 |
|
指定されたオフセットからLOBにデータを書き込みます。 |
|
LOBの終わり以降にバッファを書き込みます。 |
97.8.1 APPENDプロシージャ
このプロシージャは、ソース内部LOBの内容を宛先LOBに追加します。ソースLOBを完全に追加します
構文
DBMS_LOB.APPEND ( dest_lob IN OUT NOCOPY BLOB, src_lob IN BLOB); DBMS_LOB.APPEND ( dest_lob IN OUT NOCOPY CLOB CHARACTER SET ANY_CS, src_lob IN CLOB CHARACTER SET dest_lob%CHARSET);
パラメータ
表97-10 APPENDプロシージャのパラメータ
パラメータ | 説明 |
---|---|
|
データを追加する内部LOBのロケータ |
|
データを読み取る内部LOBのロケータ |
例外
表97-11 APPENDプロシージャの例外
例外 | 説明 |
---|---|
|
ソースまたは宛先LOBのいずれかが |
|
問合せまたはPDMLパラレル実行サーバー内でLOB書込みが実行できません。 |
使用上のノート
-
オープン/クローズ・インタフェース内のLOB操作のラップは必須ではありません。操作を実行する前にLOBをオープンしなかった場合、LOB列のファンクション索引およびドメイン索引は、コール中に更新されます。ただし、操作を実行する前にLOBをオープンした場合は、トランザクションのコミットを実行する前にクローズする必要があります。内部LOBがクローズされるときに、LOB列のファンクション索引およびドメイン索引が更新されます。
オープン/クローズAPI内のLOB操作をラップしなかった場合、ファンクション索引およびドメイン索引はLOBへ書き込むたびに更新されます。これにより、パフォーマンスに悪影響を及ぼす可能性があります。したがって、LOBへの書込み操作を
OPEN
またはCLOSE
文の中に囲むことをお薦めします。 -
アーカイブされているLOBで
APPEND
をコールした場合は、最初のバイトが書き込まれる前にLOBが暗黙的に取得されます。 -
DBFSリンクであるSecureFiles LOBで
APPEND
がコールされると、例外が発生します。
参照:
このプロシージャの使用方法の詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください。
97.8.2 CLOB2FILEプロシージャ
このプロシージャは、CLOB
の内容をbfile
に書き込みます。このプロシージャは、非推奨となったdbms_xslprocessor.clob2file
から内部的にコールされます。
構文
DBMS_LOB.CLOB2FILE( src_cl IN CLOB, file_loc IN VARCHAR2, file_name IN VARCHAR2, csid IN NUMBER := 0, open_mode IN VARCHAR2 :='wb');
パラメータ
表97-12 CLOB2FILEプロシージャのパラメータ
パラメータ | 説明 |
---|---|
|
ファイルに書き込むソースCLOBロケータ |
|
ファイルが存在しているディレクトリ・オブジェクト名 |
|
ファイル名 |
|
CLOBロケータの文字セットID
|
|
出力ファイルをオープンするモード。
wb です。 |
97.8.3 CLOSEプロシージャ
このプロシージャは、オープンしている内部または外部LOBをクローズします。
構文
DBMS_LOB.CLOSE ( lob_loc IN OUT NOCOPY BLOB); DBMS_LOB.CLOSE ( lob_loc IN OUT NOCOPY CLOB CHARACTER SET ANY_CS); DBMS_LOB.CLOSE ( file_loc IN OUT NOCOPY BFILE);
パラメータ
表97-13 CLOSEプロシージャのパラメータ
パラメータ | 説明 |
---|---|
|
LOBロケータ。詳細は、「操作上のノート」を参照してください。 |
例外
BFILE
は存在しているが、オープンしていない場合、エラーは戻りません。エラーは、LOBがオープンしていない場合に戻されます。
使用上のノート
CLOSE
では、内部または外部LOBのいずれの場合もサーバーへのラウンドトリップが必要です。内部LOBの場合、CLOSE
はクローズ・コールに依存するその他のコードをトリガーし、外部LOB (BFILE
)の場合、CLOSE
はサーバー側のオペレーティング・システム・ファイルを実際にクローズします。
オープン/クローズ・インタフェース内のすべてのLOB操作のラップは必須ではありません。ただし、LOBをオープンしている場合は、トランザクションのコミットを実行する前にクローズする必要があり、クローズしない場合は、エラーが発生します。内部LOBがクローズされるときに、LOB列のファンクション索引およびドメイン索引が更新されます。
トランザクションによってオープンされたすべてのLOBをクローズする前にトランザクションをコミットすると、エラーが発生します。エラーが戻された場合、LOBのオープンは廃棄されますが、トランザクションのコミットは正常に行われます。したがって、そのトランザクションにおけるLOBおよび非LOBデータの変更はすべてコミットされますが、ドメイン索引およびファンクションベースの索引は更新されません。このような場合は、LOB列のファンクション索引およびドメイン索引を再構築する必要があります。
参照:
このプロシージャの使用方法の詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください。
97.8.4 COMPAREファンクション
このファンクションは、2つのLOB全体、または2つのLOBの一部を比較します。
構文
DBMS_LOB.COMPARE ( lob_1 IN BLOB, lob_2 IN BLOB, amount IN INTEGER := DBMS_LOB.LOBMAXSIZE, offset_1 IN INTEGER := 1, offset_2 IN INTEGER := 1) RETURN INTEGER; DBMS_LOB.COMPARE ( lob_1 IN CLOB CHARACTER SET ANY_CS, lob_2 IN CLOB CHARACTER SET lob_1%CHARSET, amount IN INTEGER := DBMS_LOB.LOBMAXSIZE, offset_1 IN INTEGER := 1, offset_2 IN INTEGER := 1) RETURN INTEGER; DBMS_LOB.COMPARE ( lob_1 IN BFILE, lob_2 IN BFILE, amount IN INTEGER, offset_1 IN INTEGER := 1, offset_2 IN INTEGER := 1) RETURN INTEGER;
プラグマ
pragma restrict_references(COMPARE, WNDS, WNPS, RNDS, RNPS);
パラメータ
表97-14 COMPAREファンクションのパラメータ
パラメータ | 説明 |
---|---|
|
最初の比較対象のLOBロケータ。 |
|
2番目の比較対象のLOBロケータ。 |
|
比較するバイト数( |
|
1番目のLOBの比較開始位置を示すオフセット(起点: 1)。バイト数または文字数で指定します。 |
|
2番目のLOBの比較開始位置を示すオフセット(起点: 1)。バイト数または文字数で指定します。 |
戻り値
-
INTEGER
: 比較が正常に行われた場合は0(ゼロ)、それ以外の場合は0(ゼロ)以外の整数が戻されます。 -
amount
、offset_1
またはoffset_2
のいずれかが有効なLOBオフセット値でない場合はNULL
が戻されます。有効なオフセットは、1からLOBMAXSIZE
の範囲内です。
使用上のノート
-
比較できるのは、同じデータ・タイプのLOB(
BLOB
タイプのLOB
と他のBLOB
、CLOB
とCLOB
、BFILE
とBFILE
)に限られます。BFILE
の場合は、この操作を行う前に、FILEOPEN
操作でファイルをあらかじめオープンしておく必要があります。 -
offset
およびamount
パラメータによって指定した範囲のデータがすべて完全に一致すると、COMPARE
により0(ゼロ)が戻されます。1番目のCLOB
が2番目より小さいと、COMPARE
によって-1が戻され、大きいと1が戻されます。 -
固定幅のnバイトの
CLOB
の場合は、COMPARE
に対する入力amountの指定が(DBMS_LOB
.LOBMAXSIZE
/n)を超えると、(DBMS_LOB
.LOBMAXSIZE
/n
)またはMax(length(clob1), length(clob2))のサイズのうち、小さい方の範囲で文字を比較します。 -
アーカイブされているLOBで
COMPARE
をコールした場合は、比較が開始される前にLOBが暗黙的に取得されます。 -
DBFSリンクであるSecureFiles LOBで
COMPARE()
がコールされると、リンクされたLOBは、可能な場合はDBFSからストリーミングされ、可能でない場合は例外が発生します。
例外
表97-15 BFILE操作に関するCOMPAREファンクションの例外
例外 | 説明 |
---|---|
|
ファイルが入力ロケータを使用してオープンされていません。 |
|
ディレクトリが存在しません。 |
|
ディレクトリに対する権限がありません。 |
|
ディレクトリがファイルのオープン後に無効となりました。 |
|
ファイルが存在しないか、またはファイルのアクセス権限がありません。 |
参照:
このプロシージャの使用方法の詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください。
97.8.5 CONVERTTOBLOBプロシージャ
このプロシージャは、ソースCLOB
またはNCLOB
インスタンスから、文字データを読み取り、指定した文字セットに変換して、変換したデータをバイナリ形式で宛先BLOB
インスタンスに書き込み、新しいオフセットを戻します。
このインタフェースは、ソースや宛先としての持続または一時LOBインスタンスのあらゆる組合せで使用できます。
構文
DBMS_LOB.CONVERTTOBLOB( dest_lob IN OUT NOCOPY BLOB, src_clob IN CLOB CHARACTER SET ANY_CS, amount IN INTEGER, dest_offset IN OUT INTEGER, src_offset IN OUT INTEGER, blob_csid IN NUMBER, lang_context IN OUT INTEGER, warning OUT INTEGER);
パラメータ
表97-16 CONVERTTOBLOBプロシージャのパラメータ
パラメータ | 説明 |
---|---|
|
宛先LOBインスタンスのLOBロケータ。 |
|
ソースLOBインスタンスのLOBロケータ。 |
|
ソースLOBから変換する文字数。 LOB全体をコピーする場合は、定数 |
|
( |
|
|
|
変換データの目的とする文字セットID。 |
|
( この情報は、ユーザーがこの情報を使用してソース・データを失ったり、誤って解釈したりすることなく継続して変換できるようにするために戻されます。最初の変換の場合、または特に必要ない場合は、デフォルト値の0(ゼロ)を使用してください。 |
|
( 現在、発生する可能性があるのは、変換不可能な文字に関する警告のみです。これは、ソースの文字が宛先の文字に正しく変換できない場合に発生します。変換不可能な文字のかわりに、デフォルトの置換文字('?'など)が使用されます。このエラー・メッセージの戻り値は、 |
使用上のノート
事前条件
CONVERTTOBLOB
プロシージャをコールする前に、次の事前条件を満たしている必要があります。
-
ソースと宛先の両方のLOBインスタンスが存在している。
-
宛先LOBが永続LOBの場合、行がロックされている。行をロックするには、
SELECT
文のFOR
UPDATE
句を使用して、LOBを選択します。
定数およびデフォルト
すべてのパラメータが必要です。各OUT
またはIN OUT
パラメータに変数を渡す必要があります。各IN
パラメータに変数または値を渡す必要があります。
表97-17に各パラメータの一般的な値の要約を示します。1列目にパラメータ、2列目に一般的な値を示し、最後の列は値を渡した結果を説明しています。値によっては定数が使用されるので注意してください。このような定数は、dbmslob.sql
パッケージ仕様部ファイルに定義されています。
表97-17 DBMS_LOB.CONVERTTOBLOBの一般的な値
パラメータ | 値 | 説明 |
---|---|---|
|
|
ファイル全体を変換します。 |
|
|
先頭から開始します。 |
|
|
先頭から開始します。 |
|
|
デフォルトの |
|
|
デフォルトの言語コンテキスト。 |
|
|
警告メッセージはありません。成功しました。 ソースの文字を正しく変換できません。 |
一般的なノート
-
blob_csid
パラメータに宛先LOBの目的の文字セットを指定する必要があります。blob_csid
には0(ゼロ)の値を渡せます。これを行う場合、データベースでは目的の文字セットがソースLOB文字セットと同じであると想定されます。 -
ソースおよび宛先の両方のLOBに対するオフセット、およびソースLOBからコピーする文字数を指定する必要があります。
amount
およびsrc_offset
値は文字単位、dest_offset
はバイト単位です。LOB全体を変換するには、amount
パラメータにLOBMAXSIZE
を指定します。 -
CONVERTTOBLOB
は、データの変換および書込み前に、必要に応じてソースまたは宛先LOBを取得します。
例外
表97-18に、このプロシージャがスローする可能性のある例外を示します。1列目は例外の文字列を示し、2列目は例外の原因となる可能性のあるエラー条件を説明しています。
表97-18 CONVERTTOBLOBプロシージャの例外
例外 | 説明 |
---|---|
|
入力パラメータのいずれかが |
|
次の1つ以上を指定します。 - - - - |
参照:
アプリケーション開発でのLOBの使用方法の詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください。
97.8.6 CONVERTTOCLOBプロシージャ
このプロシージャは、ソースBLOB
インスタンスを取得し、指定した文字セットを使用して、ソース・インスタンスのバイナリ・データを文字データに変換し、文字データを宛先CLOB
またはNCLOB
インスタンスに書き込み、新しいオフセットを戻します。
このインタフェースは、ソースや宛先としての持続または一時LOBインスタンスのあらゆる組合せで使用できます。
構文
DBMS_LOB.CONVERTTOCLOB( dest_lob IN OUT NOCOPY CLOB CHARACTER SET ANY_CS, src_blob IN BLOB, amount IN INTEGER, dest_offset IN OUT INTEGER, src_offset IN OUT INTEGER, blob_csid IN NUMBER, lang_context IN OUT INTEGER, warning OUT INTEGER);
パラメータ
表97-19 CONVERTTOCLOBプロシージャのパラメータ
パラメータ | 説明 |
---|---|
|
宛先LOBインスタンスのLOBロケータ。 |
|
ソースLOBインスタンスのLOBロケータ。 |
|
ソースLOBから変換するバイト数。 BLOB全体をコピーする場合は、定数 |
|
|
|
|
|
ソース・データの文字セットID。 |
|
( この情報は、ユーザーがこの情報を使用してソース・データを失ったり、誤って解釈したりすることなく継続して変換できるようにするために戻されます。最初の変換の場合、または特に必要ない場合は、デフォルト値の0(ゼロ)を使用してください。 |
|
警告メッセージです。このパラメータは、変換時に何らかの異常が発生したことを示します。警告メッセージを確認する必要があります。 現在、発生する可能性があるのは、変換不可能な文字に関する警告のみです。これは、ソースの文字が宛先の文字に正しく変換できない場合に発生します。変換不可能な文字のかわりに、デフォルトの置換文字('?'など)が使用されます。このエラー・メッセージの戻り値は、 |
使用上のノート
事前条件
CONVERTTOCLOB
プロシージャをコールする前に、次の事前条件を満たしている必要があります。
-
ソースと宛先の両方のLOBインスタンスが存在している。
-
宛先LOBが永続LOBの場合、
CONVERTTOCLOB
プロシージャをコールする前に行がロックされている。行をロックするには、SELECT
文のFOR UPDATE
句を使用して、LOBを選択します。
定数およびデフォルト
すべてのパラメータが必要です。各OUT
またはIN OUT
パラメータに変数を渡す必要があります。各IN
パラメータに変数または値を渡す必要があります。
表97-20に各パラメータの一般的な値の要約を示します。1列目にパラメータ、2列目に一般的な値を示し、最後の列は値を渡した結果を説明しています。値によっては定数が使用されるので注意してください。このような定数は、dbmslob.sql
パッケージ仕様部ファイルに定義されています。
表97-20 DBMS_LOB.CONVERTTOCLOBの一般的な値
パラメータ | 値 | 説明 |
---|---|---|
|
|
ファイル全体を変換します。 |
|
|
先頭から開始します。 |
|
|
先頭から開始します。 |
|
|
デフォルトの |
|
|
デフォルトの言語コンテキスト。 |
|
|
警告メッセージはありません。成功しました。 ソースの文字を正しく変換できません。 |
一般的なノート
-
blob_csid
パラメータにソースLOBの目的の文字セットを指定する必要があります。blob_csid
には0(ゼロ)の値を渡せます。そうすると、データベースで、目的の文字セットが宛先LOB文字セットと同じであるとみなされます。 -
ソースおよび宛先の両方のLOBに対するオフセット、およびソースLOBからコピーする文字数を指定する必要があります。
amount
およびsrc_offset
値はバイト単位でdest_offset
は文字単位です。LOB全体を変換するには、amount
パラメータにLOBMAXSIZE
を指定します。 -
CONVERTTOCLOB
は、データの変換および書込み前に、必要に応じてソースまたは宛先LOB(あるいはその両方)を取得します。
例外
表97-21 CONVERTTOCLOBプロシージャの例外
例外 | 説明 |
---|---|
|
入力パラメータのいずれかが |
|
次の1つ以上を指定します。 - - - - |
参照:
アプリケーション開発でのLOBの使用方法の詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください。
97.8.7 COPYプロシージャ
このプロシージャは、ソース内部LOBの全体または一部を宛先内部LOBにコピーします。ソースおよび宛先の両方のLOBに対するオフセット、およびコピーするバイト数または文字数を指定できます。
構文
DBMS_LOB.COPY ( dest_lob IN OUT NOCOPY BLOB, src_lob IN BLOB, amount IN INTEGER, dest_offset IN INTEGER := 1, src_offset IN INTEGER := 1); DBMS_LOB.COPY ( dest_lob IN OUT NOCOPY CLOB CHARACTER SET ANY_CS, src_lob IN CLOB CHARACTER SET dest_lob%CHARSET, amount IN INTEGER, dest_offset IN INTEGER := 1, src_offset IN INTEGER := 1);
パラメータ
表97-22 COPYプロシージャのパラメータ
パラメータ | 説明 |
---|---|
|
コピー先のLOBロケータ。 |
|
コピー元のLOBロケータ。 |
|
コピーするバイト数( |
|
宛先LOBのコピー開始位置を示すオフセット(起点: 1)。バイト数または文字数で指定します。 |
|
ソースLOBのコピー開始位置を示すオフセット(起点: 1)。バイト数または文字数で指定します。 |
例外
表97-23 COPYプロシージャの例外
例外 | 説明 |
---|---|
|
入力パラメータのいずれかが |
|
次のいずれかです。 - - - - |
|
問合せまたはPDMLパラレル実行サーバー内でLOB書込みが実行できません。 |
使用上のノート
-
宛先LOBに指定したオフセットが、現在そのLOBに格納されているデータの終わりを超えている場合は、宛先
BLOB
またはCLOB
に、0(ゼロ)バイトのFILLERまたは空白がそれぞれ挿入されます。オフセットが宛先LOBの現行の長さより小さい場合、既存のデータは上書きされます。 -
ソースLOBのデータ長を超える量を指定してもエラーにはなりません。したがって、ソースLOBのデータを、
src_offset
からソースLOBの終了までコピーする大量のコピーを指定できます。 -
オープン/クローズ・インタフェース内のLOB操作のラップは必須ではありません。操作を実行する前にLOBをオープンしなかった場合、LOB列のファンクション索引およびドメイン索引は、コール中に更新されます。ただし、操作を実行する前にLOBをオープンした場合は、トランザクションのコミットを実行する前にクローズする必要があります。内部LOBがクローズされるときに、LOB列のファンクション索引およびドメイン索引が更新されます。
-
オープン/クローズAPI内のLOB操作をラップしなかった場合、ファンクション索引およびドメイン索引はLOBへ書き込むたびに更新されます。これにより、パフォーマンスに悪影響を及ぼす可能性があります。したがって、LOBへの書込み操作を
OPEN
またはCLOSE
文の中に囲むことをお薦めします。 -
コピー前に、ソースおよび宛先LOBが現在アーカイブされている場合は、それらが取得されます。完全に上書きする場合、宛先LOBは取り出されません。
-
ソースLOBがDBFSリンクの場合、データは、可能な場合はDBFSからストリーミングされ、可能でない場合は例外が発生します。宛先LOBがDBFSリンクの場合は、例外が発生します。
参照:
このプロシージャの使用方法の詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください。
97.8.8 COPY_DBFS_LINKプロシージャ
このプロシージャは、ソースLOBのDBFSリンクを宛先LOBにコピーします。
構文
DBMS_LOB.COPY_DBFS_LINK ( lob_loc_dst IN OUT BLOB, lob_loc_src IN BLOB, flags IN PLS_INTEGER DEFAULT DBFS_LINK_NOCACHE); DBMS_LOB.COPY_DBFS_LINK ( lob_loc_dst IN OUT CLOB CHARACTER SET ANY_CS, lob_loc_src IN CLOB CHARACTER SET ANY_CS, flags IN PLS_INTEGER DEFAULT DBFS_LINK_NOCACHE);
パラメータ
表97-24 COPY_DBFS_LINKプロシージャのパラメータ
パラメータ | 説明 |
---|---|
|
|
|
参照のコピー元のLOB。 |
|
|
例外
表97-25 COPY_DBFS_LINKプロシージャの例外
例外 | 説明 |
---|---|
|
|
|
|
|
ソースLOBがすでに取得されているか、アーカイブされていないか、またはロケータの取得後にLOBが(変更されたかどうかに関係なく)移行されています。 |
97.8.9 COPY_FROM_DBFS_LINK
このプロシージャは、アーカイブされたSecureFiles LOBデータをDBFS HSMストアから取得し、データベースにコピーします。
構文
DBMS_LOB.COPY_FROM_DBFS_LINK ( lob_loc IN OUT BLOB); DBMS_LOB.COPY_FROM_DBFS_LINK ( lob_loc IN OUT CLOB CHARACTER SET ANY_CS);
パラメータ
表97-26 COPY_FROM_DBFS_LINKプロシージャのパラメータ
パラメータ | 説明 |
---|---|
|
アーカイブから取得されるLOB |
使用上のノート
COPY_FROM_DBFS_LINK
によって基礎となるDBFSファイルは削除されません。
LOBが正常に取得されると、COPY_FROM_DBFS_LINK
では暗黙的に成功が返されます。
例外
表97-27 COPY_FROM_DBFS_LINKプロシージャの例外
例外 | 説明 |
---|---|
|
|
|
LOBがすでに取得されており、取得後に変更されているかどうか、ロケータの取得後にLOBが(変更されたかどうかに関係なく)移行されているかどうか。 |
97.8.10 CREATETEMPORARYプロシージャ
このプロシージャは、一時BLOB
またはCLOB
およびそれに対応する索引をユーザーのデフォルト一時表領域に作成します。
構文
DBMS_LOB.CREATETEMPORARY ( lob_loc IN OUT NOCOPY BLOB, cache IN BOOLEAN, dur IN PLS_INTEGER := DBMS_LOB.SESSION); DBMS_LOB.CREATETEMPORARY ( lob_loc IN OUT NOCOPY CLOB CHARACTER SET ANY_CS, cache IN BOOLEAN, dur IN PLS_INTEGER := 10);
パラメータ
表97-28 CREATETEMPORARYプロシージャのパラメータ
パラメータ | 説明 |
---|---|
|
LOBロケータ。詳細は、「操作上のノート」を参照してください。 |
|
LOBをバッファ・キャッシュに読み込むかどうかを指定します。 |
|
2つの事前定義の継続時間(
|
参照:
-
このプロシージャの使用方法の詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください。
-
NOCOPYの詳細および一時LOBをパラメータとして渡す方法の詳細は、『Oracle Database PL/SQL言語リファレンス』を参照してください。
97.8.11 DBFS_LINK_GENERATE_PATHファンクション
このサブプログラムは、DBFSリンクの作成に使用する一意のファイル・パス名を戻します。
構文
DBMS_LOB.DBFS_LINK_GENERATE_PATH ( lob_loc IN BLOB, storage_dir IN VARCHAR2) RETURN VARCHAR2; DBMS_LOB.DBFS_LINK_GENERATE_PATH ( lob_loc IN CLOB CHARACTER SET ANY_CS, storage_dir IN VARCHAR2) RETURN VARCHAR2;
プラグマ
PRAGMA RESTRICT_REFERENCES(dbfs_link_generate_path, WNDS, RNDS, WNPS, RNPS);
パラメータ
表97-29 DBFS_LINK_GENERATE_PATHファンクションのパラメータ
パラメータ | 説明 |
---|---|
|
DBFSから取得されるLOB。 |
|
ファイルの親ディレクトリとなるDBFSディレクトリ。 |
例外
表97-30 DBFS_LINK_GENERATE_PATHファンクションの例外
例外 | 説明 |
---|---|
|
|
使用上のノート
アーカイブに使用できるグローバルに一意なファイル・パス名を戻します。これは、このファンクションの各種LOBまたはLOBの各バージョンを対象としたすべてのコールで、グローバルに一意であることが保証されています。同一のLOBおよびバージョンでは、常に同じ名前になります。
97.8.12 ERASEプロシージャ
このプロシージャは、内部LOB全体、または内部LOBの一部を消去します。
構文
DBMS_LOB.ERASE ( lob_loc IN OUT NOCOPY BLOB, amount IN OUT NOCOPY INTEGER, offset IN INTEGER := 1); DBMS_LOB.ERASE ( lob_loc IN OUT NOCOPY CLOB CHARACTER SET ANY_CS, amount IN OUT NOCOPY INTEGER, offset IN INTEGER := 1);
パラメータ
表97-31 ERASEプロシージャのパラメータ
パラメータ | 説明 |
---|---|
|
消去するLOBのロケータ。詳細は、「操作上のノート」を参照してください。 |
|
消去するバイト数( |
|
LOBの先頭からの絶対オフセット(起点: 1)。 |
使用上のノート
-
LOBの中央部のデータが消去されると、
BLOB
またはCLOB
には、0(ゼロ)バイトのFILLERまたは空白がそれぞれ書き込まれます。 -
指定した数を消去する前にLOB値の終わりに達した場合、実際に消去されたバイト数または文字数は、
amount
パラメータで指定した数と異なる場合があります。実際に消去された文字数またはバイト数は、amount
パラメータに戻されます。 -
ERASE
は、アーカイブされているLOBを取得します。ただし、消去がLOB全体に適用される場合を除きます。 -
削除するLOBがDBFSリンクの場合、例外が発生します。
ノート:
LOBの長さは、LOBのセクションを消去しても減りません。LOB値の長さを減らす方法は、「TRIMプロシージャ」を参照してください。
例外
表97-32 ERASEプロシージャの例外
例外 | 説明 |
---|---|
|
入力パラメータのいずれかが |
|
次のいずれかです。 - - |
|
問合せまたはPDMLパラレル実行サーバー内でLOB書込みが実行できません。 |
使用上のノート
オープン/クローズ・インタフェース内のLOB操作のラップは必須ではありません。操作を実行する前にLOBをオープンしなかった場合、LOB列のファンクション索引およびドメイン索引は、コール中に更新されます。ただし、操作を実行する前にLOBをオープンした場合は、トランザクションのコミットを実行する前にクローズする必要があります。内部LOBがクローズされるときに、LOB列のファンクション索引およびドメイン索引が更新されます。
オープン/クローズAPI内のLOB操作をラップしなかった場合、ファンクション索引およびドメイン索引はLOBへ書き込むたびに更新されます。これにより、パフォーマンスに悪影響を及ぼす可能性があります。したがって、LOBへの書込み操作をOPEN
またはCLOSE
文の中に囲むことをお薦めします。
参照:
-
このプロシージャの使用方法の詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください。
97.8.13 FILECLOSEプロシージャ
このプロシージャは、入力ロケータによってすでにオープンされているBFILE
をクローズします。
ノート:
データベースには、BFILE
に対する読取り専用アクセスしかありません。つまり、データベースを介してBFILE
に書き込むことはできません。
構文
DBMS_LOB.FILECLOSE ( file_loc IN OUT NOCOPY BFILE);
パラメータ
表97-33 FILECLOSEプロシージャのパラメータ
パラメータ | 説明 |
---|---|
|
クローズする |
例外
表97-34 FILECLOSEプロシージャの例外
例外 | 説明 |
---|---|
|
|
|
ファイルが入力ロケータを使用してオープンされていません。 |
|
ディレクトリが存在しません。 |
|
ディレクトリに対する権限がありません。 |
|
ディレクトリがファイルのオープン後に無効となりました。 |
|
ファイルが存在しないか、またはファイルのアクセス権限がありません。 |
参照:
-
このプロシージャの使用方法の詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください。
97.8.14 FILECLOSEALLプロシージャ
このプロシージャは、セッションでオープンされたすべてのBFILE
をクローズします。
構文
DBMS_LOB.FILECLOSEALL;
例外
表97-35 FILECLOSEALLプロシージャの例外
例外 | 説明 |
---|---|
|
セッションでオープンされたファイルはありません。 |
参照:
-
このプロシージャの使用方法の詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください。
97.8.15 FILEEXISTSファンクション
このファンクションは、指定したBFILE
ロケータが、サーバーのファイル・システムに実際に存在しているファイルを指しているかどうかを検証します。
構文
DBMS_LOB.FILEEXISTS ( file_loc IN BFILE) RETURN INTEGER;
プラグマ
pragma restrict_references(FILEEXISTS, WNDS, RNDS, WNPS, RNPS);
パラメータ
表97-36 FILEEXISTSファンクションのパラメータ
パラメータ | 説明 |
---|---|
|
|
戻り値
表97-37 FILEEXISTSファンクションの戻り値
戻り値 | 説明 |
---|---|
|
物理ファイルが存在しません。 |
|
物理ファイルが存在します。 |
例外
表97-38 FILEEXISTSファンクションの例外
例外 | 説明 |
---|---|
|
ディレクトリが存在しません。 |
|
ディレクトリに対する権限がありません。 |
|
ディレクトリがファイルのオープン後に無効となりました。 |
参照:
-
このプロシージャの使用方法の詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください。
97.8.16 FILEGETNAMEプロシージャ
このプロシージャは、指定したBFILE
ロケータのディレクトリ・オブジェクトとファイル名を判別します。
ロケータに割り当てられたディレクトリ・オブジェクト名とファイル名を示すのみで、物理ファイルまたはディレクトリが実際に存在しているかどうかは判別しません。
dir_alias
バッファの最大値は30で、パス名全体の最大値は2000です。
構文
DBMS_LOB.FILEGETNAME ( file_loc IN BFILE, dir_alias OUT VARCHAR2, filename OUT VARCHAR2);
パラメータ
表97-39 FILEGETNAMEプロシージャのパラメータ
パラメータ | 説明 |
---|---|
|
|
|
ディレクトリ・オブジェクト名 |
|
|
例外
表97-40 FILEGETNAMEプロシージャの例外
例外 | 説明 |
---|---|
|
入力パラメータのいずれかが |
|
|
参照:
このプロシージャの使用方法の詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください。
97.8.17 FILEISOPENファンクション
このファンクションは、BFILE
が特定のFILE
ロケータでオープンされたかどうかを検証します。
構文
DBMS_LOB.FILEISOPEN ( file_loc IN BFILE) RETURN INTEGER;
プラグマ
PRAGMA RESTRICT_REFERENCES(fileisopen, WNDS, RNDS, WNPS, RNPS
);
パラメータ
表97-41 FILEISOPENファンクションのパラメータ
パラメータ | 説明 |
---|---|
|
|
戻り値
INTEGER
: 0 =ファイルはオープンされていません。1 =ファイルはオープンされています。
使用上のノート
入力FILE
ロケータがFILEOPEN
プロシージャに渡されていない場合、そのファイルはこのロケータによってオープンされていないとみなされます。ただし、別のロケータがこのファイルをオープンしている可能性はあります。つまり、オープンされているかどうかは特定のロケータと関連付けられています。
例外
表97-42 FILEISOPENファンクションの例外
例外 | 説明 |
---|---|
|
ディレクトリが存在しません。 |
|
ディレクトリに対する権限がありません。 |
|
ディレクトリがファイルのオープン後に無効となりました。 |
参照:
-
このプロシージャの使用方法の詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください。
97.8.18 FILEOPENプロシージャ
このプロシージャは、BFILE
を読取り専用アクセスでオープンします。データベースを介してBFILE
に書き込むことはできません。
構文
DBMS_LOB.FILEOPEN ( file_loc IN OUT NOCOPY BFILE, open_mode IN BINARY_INTEGER := file_readonly);
パラメータ
表97-43 FILEOPENプロシージャのパラメータ
パラメータ | 説明 |
---|---|
|
|
|
ファイル・アクセスは読取り専用です。 |
例外
表97-44 FILEOPENプロシージャの例外
例外 | 説明 |
---|---|
|
|
|
|
|
セッション内のオープン・ファイル数が |
|
|
|
ディレクトリがファイルのオープン後に無効となりました。 |
|
ファイルが存在しないか、またはファイルのアクセス権限がありません。 |
参照:
-
このプロシージャの使用方法の詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください。
97.8.19 FRAGMENT_DELETEプロシージャ
このプロシージャは、LOBからの長さを指定した場合、指定したオフセット位置にあるデータを削除します。LOB内の指定したオフセット位置の後にあるすべてのデータをリライトする必要はありません。
構文
DBMS_LOB.FRAGMENT_DELETE ( lob_loc IN OUT NOCOPY BLOB, amount IN INTEGER, offset IN INTEGER); DBMS_LOB.FRAGMENT_DELETE ( lob_loc IN OUT NOCOPY CLOB CHARACTER SET ANY_CS, amount IN INTEGER, offset IN INTEGER);
パラメータ
表97-45 FRAGMENT_DELETEプロシージャのパラメータ
パラメータ | 説明 |
---|---|
|
LOBロケータ。詳細は、「操作上のノート」を参照してください。 |
|
LOBから削除するバイト数( |
|
削除を開始するLOB内のオフセット位置を示すバイト数( |
例外
表97-46 FRAGMENT_DELETEプロシージャの例外
例外 | 説明 |
---|---|
|
パラメータ値が無効でした。 |
|
問合せ時に操作を実行できません。 |
|
|
|
LOBの終わりを超えて |
97.8.20 FRAGMENT_INSERTプロシージャ
このプロシージャは、指定したデータ(最大32K)を、LOB内の指定したオフセット位置に挿入します。
構文
DBMS_LOB.FRAGMENT_INSERT ( lob_loc IN OUT NOCOPY BLOB, amount IN INTEGER, offset IN INTEGER, buffer IN RAW); DBMS_LOB.FRAGMENT_INSERT ( lob_loc IN OUT NOCOPY CLOB CHARACTER SET ANY_CS, amount IN INTEGER, offset IN INTEGER, buffer IN VARCHAR2 CHARACTER SET lob_loc%CHARSET);
パラメータ
表97-47 FRAGMENT_INSERTプロシージャのパラメータ
パラメータ | 説明 |
---|---|
|
LOBロケータ。詳細は、「操作上のノート」を参照してください。 |
|
LOBに挿入するバイト数(BLOB)または文字数(CLOB/NCLOB)。 |
|
挿入を開始するLOB内のオフセット位置を示すバイト数(BLOB)または文字数(CLOB/NCLOB)。 |
|
LOBに挿入するデータ。 |
例外
表97-48 FRAGMENT_INSERTプロシージャの例外
例外 | 説明 |
---|---|
|
パラメータ値が無効でした。 |
|
問合せ時に操作を実行できません。 |
|
|
|
LOBの終わりを超えて |
使用上のノート
FRAGMENT_INSERT
は、LOBに対する操作を実行する前に、必要に応じてLOBを取得します。
97.8.21 FRAGMENT_MOVEプロシージャ
このプロシージャは、指定したオフセット位置から新しく指定したオフセット位置に、バイト単位(BLOB)または文字単位(CLOB/NCLOB)で移動します。
構文
DBMS_LOB.FRAGMENT_MOVE ( lob_loc IN OUT NOCOPY BLOB, amount IN INTEGER, src_offset IN INTEGER, dest_offset IN INTEGER); DBMS_LOB.FRAGMENT_MOVE ( lob_loc IN OUT NOCOPY CLOB CHARACTER SET ANY_CS, amount IN INTEGER, src_offset IN INTEGER, dest_offset IN INTEGER);
パラメータ
表97-49 FRAGMENT_MOVEプロシージャのパラメータ
パラメータ | 説明 |
---|---|
|
LOBロケータ。詳細は、「操作上のノート」を参照してください。 |
|
LOB内の移動するバイト数( |
|
データの挿入を開始するLOB内のオフセット位置を示すバイト数( |
|
データの削除を開始するLOB内のオフセット位置を示すバイト数( |
例外
表97-50 FRAGMENT_MOVEプロシージャの例外
例外 | 説明 |
---|---|
|
パラメータ値が無効でした。 |
|
問合せ時に操作を実行できません。 |
|
|
|
LOBの終わりを超えて |
使用上のノート
-
すべてのオフセット位置は事前移動オフセット位置です。
-
LOBの終わりを2以上超えてオフセット位置を設定することはできません。
-
FRAGMENT_MOVE
は、LOBに対する操作を実行する前に、必要に応じてLOBを取得します。
97.8.22 FRAGMENT_REPLACEプロシージャ
このプロシージャは、指定したオフセット位置にあるデータを指定したデータ(32k以下)で置き換えます。
構文
DBMS_LOB.FRAGMENT_REPLACE ( lob_loc IN OUT NOCOPY BLOB, old_amount IN INTEGER, new_amount IN INTEGER, offset IN INTEGER, buffer IN RAW); DBMS_LOB.FRAGMENT_REPLACE ( lob_loc IN OUT NOCOPY CLOB CHARACTER SET ANY_CS, old_amount IN INTEGER, new_amount IN INTEGER, offset IN INTEGER, buffer IN VARCHAR2 CHARACTER SET lob_loc%CHARSET);
パラメータ
表97-51 FRAGMENT_REPLACEファンクションのパラメータ
パラメータ | 説明 |
---|---|
|
LOBロケータ。詳細は、「操作上のノート」を参照してください。 |
|
LOB内で置き換えるバイト数( |
|
LOBに書き込むバイト数( |
|
データの挿入を開始するLOB内のオフセット位置を示すバイト数(BLOB)または文字数( |
|
LOBに挿入するデータ。 |
例外
表97-52 FRAGMENT_REPLACEプロシージャの例外
例外 | 説明 |
---|---|
|
パラメータ値が無効でした。 |
|
問合せ時に操作を実行できません。 |
|
|
|
LOBの終わりを超えて |
使用上のノート
-
このプロシージャを起動することは、オフセット位置の既存のバイト数/文字数を削除して、オフセット位置に新しいバイト数/文字数を挿入することと同様です。
-
FRAGMENT_REPLACE
は、LOBに対する操作を実行する前に、必要に応じてLOBを取得します。
97.8.23 FREETEMPORARYプロシージャ
このプロシージャは、デフォルト一時表領域内の一時BLOB
またはCLOB
を解放します。
構文
DBMS_LOB.FREETEMPORARY ( lob_loc IN OUT NOCOPY BLOB); DBMS_LOB.FREETEMPORARY ( lob_loc IN OUT NOCOPY CLOB CHARACTER SET ANY_CS);
パラメータ
表97-53 FREETEMPORARYプロシージャのパラメータ
パラメータ | 説明 |
---|---|
|
LOBロケータ。詳細は、「操作上のノート」を参照してください。 |
使用上のノート
-
新しい一時LOBの作成時に、同じ継続時間(セッション、コール)で使用されている一時LOBが存在しない場合は、新しい一時LOBセグメントが作成されます。一時LOBを解放すると、その一時LOBによって消費されていた領域が一時セグメントに解放されます。同じ継続時間が指定されているその他の一時LOBが存在しない場合は、一時セグメントも解放されます。
-
FREETEMPORARY
へのコール後、解放されたLOBロケータには無効のマークが設定されます。 -
無効のLOBロケータが、OCIの
OCILobLocatorAssign
を使用して、またはPL/SQLの割当て操作によって別のLOBロケータに割り当てられている場合、割当て先も解放され、無効のマークが設定されます。
参照:
このプロシージャの使用方法の詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください。
97.8.24 GET_DBFS_LINKファンクション
このファンクションは、指定したSecureFile LOBのDBFSパス名を戻します。
構文
DBMS_LOB.GET_DBFS_LINK ( lob_loc IN BLOB, storage_path OUT VARCHAR2(DBFS_LINK_PATH_MAX_SIZE), lob_length OUT NUMBER); DBMS_LOB.GET_DBFS_LINK ( lob_loc IN CLOB CHARACTER SET ANY_CS, storage_path OUT VARCHAR2(DBFS_LINK_PATH_MAX_SIZE), lob_length OUT NUMBER);
パラメータ
表97-54 GET_DBFS_LINKファンクションのパラメータ
パラメータ | 説明 |
---|---|
|
DBFSから取得されるLOB。 |
|
DBFSに格納されているLOBへのパス。 |
|
DBFSへの書込み時点でのLOBの長さ。 |
戻り値
アーカイブID。
例外
表97-55 GET_DBFS_LINKファンクションの例外
例外 | 説明 |
---|---|
|
|
|
LOBがすでに取得されており、取得後に変更されている。または、ロケータの取得後にLOBが(変更されたかどうかに関係なく)移行されている。 |
97.8.25 GET_DBFS_LINK_STATEプロシージャ
GET_DBFS_LINK_STATE
は、指定したSecureFileの現在のリンク状態を取得します。
構文
DBMS_LOB.GET_DBFS_LINK_STATE ( lob_loc IN BLOB, storage_path OUT VARCHAR2(DBFS_LINK_PATH_MAX_SIZE), state OUT NUMBER, cached OUT BOOLEAN); DBMS_LOB.GET_DBFS_LINK_STATE ( lob_loc IN CLOB CHARACTER SET ANY_CS, storage_path OUT VARCHAR2(DBFS_LINK_PATH_MAX_SIZE), state OUT NUMBER, cached OUT BOOLEAN);
パラメータ
表97-56 GET_DBFS_LINK_STATEプロシージャのパラメータ
パラメータ | 説明 |
---|---|
|
アーカイブから取得されるLOB |
|
DBFS HSMストアに格納されているLOBへのパス。 |
|
|
|
LOBがアーカイブされており、アーカイブ時にキャッシュされるように指定されている場合。 |
例外
表97-57 GET_DBFS_LINK_STATEプロシージャの例外
例外 | 説明 |
---|---|
|
|
使用上のノート
-
LOBがアーカイブされていない場合、状態は
DBMS_LOB
.DBFS_LINK_NEVER
に設定されます。LOBがアーカイブされている場合、状態はDBMS_LOB
.DBFS_LINK_YES
に設定されます。LOBが以前にアーカイブから取得されている場合、状態はDBFS_LINK_NO
に設定されます。 -
LOBがアーカイブされたにもかかわらず、RDBMSに残されている場合、
cached
はTRUE
に設定されます。データがリンクの作成後に削除された場合、cached
はFALSE
に設定され、状態がDBMS_LOB
.DBFS_LINK_NEVER
の場合はNULL
に設定されます。
97.8.26 GETCONTENTTYPEファンクション
このプロシージャは、SETCONTENTTYPEプロシージャを使用して以前設定したコンテンツ・タイプ文字列を戻します。
構文
DBMS_LOB.GETCONTENTTYPE ( lob_loc IN BLOB) RETURN VARCHAR2; DBMS_LOB.GETCONTENTTYPE ( lob_loc IN CLOB CHARACTER SET ANY_CS) RETURN VARCHAR2;
プラグマ
PRAGMA RESTRICT_REFERENCES(getcontenttype, WNDS, RNDS, WNPS, RNPS);
パラメータ
表97-58 GETCONTENTTYPEファンクションのパラメータ
パラメータ | 説明 |
---|---|
|
コンテンツ・タイプを取得するLOB。 |
戻り値
戻されたコンテンツ・タイプ。
SecureFiles LOBにcontenttype
が関連付けられていない場合、GETCONTENTTYPE()
はNULL
を戻します。
例外
表97-59 GETCONTENTTYPEファンクションの例外
例外 | 説明 |
---|---|
|
|
関連項目
97.8.27 GET_STORAGE_LIMITファンクション
このファンクションは、指定したLOBのLOB記憶域制限を戻します。
構文
DBMS_LOB.GET_STORAGE_LIMIT ( lob_loc IN CLOB CHARACTER SET ANY_CS) RETURN INTEGER; DBMS_LOB.GET_STORAGE_LIMIT ( lob_loc IN BLOB) RETURN INTEGER;
プラグマ
PRAGMA RESTRICT_REFERENCES(get_storage_limit, WNDS, RNDS, WNPS, RNPS);
パラメータ
表97-60 GET_STORAGE_LIMITファンクションのパラメータ
パラメータ | 説明 |
---|---|
|
LOBロケータ。詳細は、「操作上のノート」を参照してください。 |
戻り値
このファンクションから戻される値は、指定したLOBロケータの最大許容サイズです。BLOB
の場合、戻り値は、LOBが存在する表領域のブロック・サイズによって異なり、表領域のブロック・サイズの(232)-1(4294967295)倍として計算されます。CLOB
/NCLOB
の場合、戻り値は、表領域のブロック・サイズの(232)-1(4294967295)倍をCLOB
/NCLOB
の文字幅で割った値になります。
使用方法
参照:
LOB記憶域制限の詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください。
97.8.28 GETCHUNKSIZEファンクション
表の作成時に、チャンク・ファクタ(表領域ブロックのバイト単位の倍数)を指定できます。これは、LOB値のアクセスまたは変更時にLOBデータ・レイヤーによって使用されるチャンク・サイズに対応します。チャンクの一部はシステム関連情報の格納に使用され、それ以外の部分にLOB値が格納されます。このファンクションは、LOB値を格納するLOBチャンクで使用される領域容量を戻します。
構文
DBMS_LOB.GETCHUNKSIZE ( lob_loc IN BLOB) RETURN INTEGER; DBMS_LOB.GETCHUNKSIZE ( lob_loc IN CLOB CHARACTER SET ANY_CS) RETURN INTEGER;
プラグマ
PRAGMA RESTRICT_REFERENCES(getchunksize, WNDS, RNDS, WNPS, RNPS);
パラメータ
表97-61 GETCHUNKSIZEファンクションのパラメータ
パラメータ | 説明 |
---|---|
|
LOBロケータ。詳細は、「操作上のノート」を参照してください。 |
戻り値
戻り値は、使用可能なチャンク・サイズ(バイト単位)です。
使用上のノート
-
基本的なLOBファイルの場合、このチャンク・サイズの倍数を使用して読取り/書込み要求を入力すると、パフォーマンスが向上します。LOBチャンクはバージョン化され、すべての書込みがチャンクを基準に行われると、余分なバージョン分割が行われず、重複もしないため、書込みの場合にはさらに利点があります。同じチャンクに対して
WRITE
コールを複数回発行するかわりに、1つのチャンク内でWRITE
コールを十分な数だけまとめることができます。これらのパフォーマンスを向上させる方法は、SecureFilesには適用されません。
-
チャンク・サイズはLOBタイプ(
BLOB
、CLOB
、NCLOB
、Unicodeまたはその他の文字セット)とは無関係です。
参照:
このプロシージャの使用方法の詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください。
97.8.29 GETLENGTHファンクション
このファンクションは、指定されたLOB値の長さを取得します。長さは、バイト数または文字数で戻されます。
BFILE
の場合に戻される長さには、EOF
(存在している場合)が含まれます。以前に行ったERASE
またはWRITE
操作でLOBに挿入された0(ゼロ)バイトまたは空白のFILLERも長さに含まれます。空の内部LOBの長さは0(ゼロ)です。
構文
DBMS_LOB.GETLENGTH ( lob_loc IN BLOB) RETURN INTEGER; DBMS_LOB.GETLENGTH ( lob_loc IN CLOB CHARACTER SET ANY_CS) RETURN INTEGER; DBMS_LOB.GETLENGTH ( file_loc IN BFILE) RETURN INTEGER;
プラグマ
pragma restrict_references(GETLENGTH, WNDS, WNPS, RNDS, RNPS);
パラメータ
表97-62 GETLENGTHファンクションのパラメータ
パラメータ | 説明 |
---|---|
|
長さが戻されるLOBのファイル・ロケータ |
戻り値
LOBの長さが、INTEGER
としてバイト数または文字数で戻されます。入力LOBがNULL
の場合または入力lob_loc
がNULL
の場合は、NULL
が戻されます。BFILE
の場合は、次の場合にエラーが戻されます。
-
lob_loc
に必要なディレクトリ権限とオペレーティング・システム権限がない場合 -
オペレーティング・システム読込みエラーのために、
lob_loc
を読み込むことができない場合参照:
このプロシージャの使用方法の詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください。
97.8.30 GETOPTIONSファンクション
このファンクションは、特定のLOBのoption_type
フィールドに対応する圧縮、重複除外および暗号化の設定を取得します。
構文
DBMS_LOB.GETOPTIONS ( lob_loc IN BLOB, option_types IN PLS_INTEGER) RETURN PLS_INTEGER; DBMS_LOB.GETOPTIONS ( lob_loc IN CLOB CHARACTER SET ANY_CS, option_types IN PLS_INTEGER) RETURN PLS_INTEGER;
パラメータ
例外
表97-64 GETOPTIONSプロシージャの例外
例外 | 説明 |
---|---|
|
パラメータ値が無効でした。 |
|
問合せ時に操作を実行できません。 |
|
|
使用上のノート
圧縮または複製解除の機能が備えられていないSecureFile列に対して、これらの機能をオンまたはオフにすることはできません。GetOptionsファンクションとSETOPTIONSプロシージャは、個々のSecureFilesに対して動作します。特定のSecureFileの機能をオフにしたり、SetOptionsによってすでにオフにされている機能をオンにすることはできますが、表の作成時にSecureFileに指定されていないオプションをオンにすることはできません。
97.8.31 INSTRファンクション
このファンクションは、指定されたオフセットを開始位置として、LOBにおけるパターンのn番目に一致した位置を戻します。
構文
DBMS_LOB.INSTR ( lob_loc IN BLOB, pattern IN RAW, offset IN INTEGER := 1, nth IN INTEGER := 1) RETURN INTEGER; DBMS_LOB.INSTR ( lob_loc IN CLOB CHARACTER SET ANY_CS, pattern IN VARCHAR2 CHARACTER SET lob_loc%CHARSET, offset IN INTEGER := 1, nth IN INTEGER := 1) RETURN INTEGER; DBMS_LOB.INSTR ( file_loc IN BFILE, pattern IN RAW, offset IN INTEGER := 1, nth IN INTEGER := 1) RETURN INTEGER;
プラグマ
pragma restrict_references(INSTR, WNDS, WNPS, RNDS, RNPS);
パラメータ
表97-65 INSTRファンクションのパラメータ
パラメータ | 説明 |
---|---|
|
検査するLOBのロケータ。詳細は、「操作上のノート」を参照してください。 |
|
検査するLOBのファイル・ロケータ。 |
|
テスト対象のパターン。パターンは、 |
|
パターン・マッチングの開始位置を示す絶対オフセット(起点: 1)。 |
|
出現番号。1から始まります。 |
戻り値
表97-66 INSTRファンクションの戻り値
戻り値 | 説明 |
---|---|
|
一致したパターンの先頭のオフセット。バイト数または文字数で示されます。 パターンが見つからない場合は0 (ゼロ)が戻されます。 |
NULL |
次のいずれかです。 - - - - |
使用上のノート
VARCHAR2
バッファ(pattern
パラメータ)の形式は、CLOB
パラメータの形式と一致する必要があります。つまり、入力LOBのパラメータのタイプがNCLOB
の場合、バッファにはNCHAR
データが含まれる必要があります。これに対して、入力LOBのパラメータのタイプがCLOB
の場合、バッファにはCHAR
データが含まれる必要があります。
BFILE
の場合は、この操作を行う前に、FILEOPEN
操作でファイルをあらかじめオープンしておく必要があります。
INSTR
など、パターン・マッチング用にRAW
またはVARCHAR2
パラメータを受け入れる操作では、パターン・パラメータまたは副文字列において、正規表現または特殊一致文字(例: SQLのLIKE
)はサポートされていません。
例外
表97-67 BFILEに関するINSTRファンクションの例外
例外 | 説明 |
---|---|
|
ファイルが入力ロケータを使用してオープンされていません。 |
|
ディレクトリが存在しません。 |
|
ディレクトリに対する権限がありません。 |
|
ディレクトリがファイルのオープン後に無効となりました。 |
|
ファイルが存在しないか、またはファイルのアクセス権限がありません。 |
参照:
-
このプロシージャの使用方法の詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください。
97.8.32 ISOPENファンクション
このファンクションは、LOBが入力ロケータを使用してすでにオープンされているかどうかをチェックします。このサブプログラムは、内部および外部LOB用です。
構文
DBMS_LOB.ISOPEN ( lob_loc IN BLOB) RETURN INTEGER; DBMS_LOB.ISOPEN ( lob_loc IN CLOB CHARACTER SET ANY_CS) RETURN INTEGER; DBMS_LOB.ISOPEN ( file_loc IN BFILE) RETURN INTEGER;
プラグマ
PRAGMA RESTRICT_REFERENCES(isopen, WNDS, RNDS, WNPS, RNPS);
パラメータ
表97-68 ISOPENファンクションのパラメータ
パラメータ | 説明 |
---|---|
|
LOBロケータ。詳細は、「操作上のノート」を参照してください。 |
|
ファイル・ロケータ。 |
戻り値
戻り値は、LOBがオープンしている場合は1、それ以外の場合は0(ゼロ)です。
使用上のノート
BFILES
の場合、オープンされているかどうかはロケータと関連付けられています。入力ロケータがOPEN
に渡されていない場合、そのBFILE
はこのロケータによってオープンされていないとみなされます。ただし、別のロケータがBFILE
をオープンしている可能性はあります。異なるロケータを使用すると、同じBFILE
上で複数のOPEN
を実行できます。
内部LOBの場合、オープンされているかどうかは、ロケータではなくそのLOBに関連付けられています。ロケータ1がLOBをオープンした場合、ロケータ2もそのLOBはオープンしているとみなします。内部LOBの場合は、LOBが実際にオープンしているかどうかを調べるにはサーバー上の状態をチェックするため、ISOPEN
でラウンドトリップが必要です。
外部LOB(BFILE
)の場合も、サーバーに状態が保持されているため、ISOPEN
でラウンドトリップが必要です。
参照:
このプロシージャの使用方法の詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください。
97.8.33 ISREMOTEファンクション
このファンクションは、LOBがデータベースに対してローカルであるか、またはリモート・データベースに属しているかを確認します。
構文
DBMS_LOB.ISREMOTE ( lob_loc IN BLOB) RETURN BOOLEAN;
DBMS_LOB.ISREMOTE ( lob_loc IN CLOB CHARACTER SET ANY_CS) RETURN BOOLEAN;
プラグマ
PRAGMA RESTRICT_REFERENCES(isremote, WNDS, RNDS, WNPS, RNPS);
パラメータ
表97-69 ISREMOTEファンクションのパラメータ
パラメータ | 説明 |
---|---|
|
|
戻り値
BOOLEAN
: データベース・リンクを介して取得されたリモートLOBの場合はTRUE
、ローカル・データベースから取得されたLOBの場合はFALSE
参照:
-
このプロシージャの使用方法の詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』の「分散LOB」の章を参照してください。
97.8.34 ISSECUREFILEファンクション
このファンクションは、渡されるLOBロケータがSecurefile LOB用の場合にTRUE
を戻します。そうでなければ、FALSE
を戻します。
構文
DBMS_LOB ISSECUREFILE( lob_loc IN BLOB) RETURN BOOLEAN;
プラグマ
PRAGMA RESTRICT_REFERENCES(issecurefile, WNDS, RNDS, WNPS, RNPS);
パラメータ
表97-70 ISSECUREFILEファンクションのパラメータ
パラメータ | 説明 |
---|---|
|
LOBロケータ。詳細は、「操作上のノート」を参照してください。 |
戻り値
このファンクションは、渡されるLOBロケータがSecurefile LOB用の場合にTRUE
を戻します。そうでなければ、FALSE
を戻します。
97.8.35 ISTEMPORARYファンクション
このファンクションはLOBインスタンスが一時的であるかどうかを判断します。
構文
DBMS_LOB.ISTEMPORARY ( lob_loc IN BLOB) RETURN INTEGER; DBMS_LOB.ISTEMPORARY ( lob_loc IN CLOB CHARACTER SET ANY_CS) RETURN INTEGER;
プラグマ
PRAGMA RESTRICT_REFERENCES(istemporary, WNDS, RNDS, WNPS, RNPS);
パラメータ
表97-71 ISTEMPORARYプロシージャのパラメータ
パラメータ | 説明 |
---|---|
|
LOBロケータ。詳細は、「操作上のノート」を参照してください。 |
戻り値
戻り値は、LOBが一時LOBとして存在している場合は1、LOBが一時LOBではないか、存在していない場合は0(ゼロ)、指定されたロケータがNULL
の場合はNULL
です。
使用上のノート
FREETEMPORARY
を指定して一時LOBを解放した場合、LOBロケータはNULL
に設定されません。したがって、ISTEMPORARY
は、解放後に明示的にNULL
に再設定されていないロケータに対して0(ゼロ)を戻します。
参照:
このプロシージャの使用方法の詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください。
97.8.36 LOADBLOBFROMFILEプロシージャ
このプロシージャは、BFILE
のデータを内部BLOB
にロードします。結果はLOADFROMFILE
と同じで、新しいオフセットを戻します。
構文
DBMS_LOB.LOADBLOBFROMFILE ( dest_lob IN OUT NOCOPY BLOB, src_bfile IN BFILE, amount IN INTEGER, dest_offset IN OUT INTEGER, src_offset IN OUT INTEGER);
パラメータ
表97-72 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
パラメータにデフォルト値を指定します。使用可能な定数およびデフォルトを次に示します。
表97-73 パラメータのデフォルト値
パラメータ | デフォルト値 | 説明 |
---|---|---|
|
|
ファイル全体をロードします。 |
|
|
先頭から開始します。 |
|
|
先頭から開始します。 |
DBMSLOB.SQL
で定義される定数
lobmaxsize CONSTANT INTEGER := DBMS_LOB.LOBMAXSIZE;
例外
表97-74 LOADBLOBFROMFILEプロシージャの例外
例外 | 説明 |
---|---|
|
入力パラメータのいずれかが |
|
次のいずれかです。 - - - - |
参照:
このプロシージャの使用方法の詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください。
97.8.37 LOADCLOBFROMFILEプロシージャ
このプロシージャは、BFILE
のデータを必要な文字セット変換を行った後、内部CLOB/NCLOB
にロードし、新しいオフセットを戻します。
構文
DBMS_LOB.LOADCLOBFROMFILE ( dest_lob IN OUT NOCOPY NOCOPY CLOB CHARACTER SET ANY_CS, src_bfile IN BFILE, amount IN INTEGER, dest_offset IN OUT INTEGER, src_offset IN OUT INTEGER, bfile_csid IN NUMBER, lang_context IN OUT INTEGER, warning OUT INTEGER);
パラメータ
表97-75 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文字を一連のバイトにマッピングする複数のコード体系が定義されています。表97-76に、このサブプログラムでサポートされているUnicodeコード体系を示します。
表97-76 サポートされている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にはロードされません。
定数
使用可能な定数およびデフォルト値を次に示します。
表97-77 LOADCLOBFROMFILEパラメータの推奨値
パラメータ | 推奨値 | 説明 |
---|---|---|
|
|
ファイル全体をロードします。 |
|
|
先頭から開始します。 |
|
|
先頭から開始します。 |
|
|
デフォルトの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;
例外
表97-78 LOADCLOBFROMFILEプロシージャの例外
例外 | 説明 |
---|---|
|
入力パラメータのいずれかが |
|
次のいずれかです。 - - - - |
参照:
このプロシージャの使用方法の詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください。
97.8.38 MOVE_TO_DBFS_LINKプロシージャ
このプロシージャは、(データベースからの)指定されたLOBデータをDBFS HSMストアにアーカイブします。
構文
DBMS_LOB.MOVE_TO_DBFS_LINK ( lob_loc IN OUT BLOB, storage_path IN VARCHAR2(dbfs_link_path_max_size), flags IN BINARY INTEGER DEFAULT DBFS_LINK_NOCACHE); DBMS_LOB.MOVE_TO_DBFS_LINK ( lob_loc IN OUT CLOB CHARACTER SET ANY_CS, storage_path IN VARCHAR2(dbfs_link_path_max_size), flags IN BINARY INTEGER DEFAULT DBFS_LINK_NOCACHE);
パラメータ
表97-79 MOVE_TO_DBFS_LINKプロシージャのパラメータ
パラメータ | 説明 |
---|---|
|
アーカイブされるLOB。 |
storage_path |
LOBが格納されるパス。 |
|
|
例外
表97-80 MOVE_TO_DBFS_LINKプロシージャの例外
例外 | 説明 |
---|---|
|
|
使用上のノート
-
このプロシージャは、LOBがすでにアーカイブされている場合、正常にアーカイブされたときと同様の結果を戻します。その場合、
DBFS_LINK_NOCACHE
が指定されているか、flags
がデフォルト設定されていると、LOBデータはRDBMSから削除されます。 -
同じLOBで同じフラグを使用してこのプロシージャを複数回コールしても、効果はありません。
-
すでにアーカイブされているLOBでこのプロシージャをコールすると、フラグの設定に応じてLOBのキャッシュ(
DBFS_LINK_CACHE
)または削除(DBFS_LINK_NOCACHE
)が実行されます。
97.8.39 OPENプロシージャ
このプロシージャは、指定されたモードで、(内部または外部)LOBをオープンします。有効なモードは読取り専用と読取り/書込みです。
構文
DBMS_LOB.OPEN ( lob_loc IN OUT NOCOPY BLOB, open_mode IN BINARY_INTEGER); DBMS_LOB.OPEN ( lob_loc IN OUT NOCOPY CLOB CHARACTER SET ANY_CS, open_mode IN BINARY_INTEGER); DBMS_LOB.OPEN ( file_loc IN OUT NOCOPY BFILE, open_mode IN BINARY_INTEGER := file_readonly);
パラメータ
表97-81 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およびラージ・オブジェクト開発者ガイド』を参照してください。
97.8.40 READプロシージャ
このプロシージャは、LOBの一部を読み込み、LOBの先頭からの絶対オフセットから開始し、指定された量のデータをbuffer
パラメータに戻します。
実際に読み込まれたバイト数または文字数は、amount
パラメータに戻されます。入力offset
がLOBの終わりを超えた位置を指している場合、amount
は0(ゼロ)に設定され、NO_DATA_FOUND
例外が発生します。
構文
DBMS_LOB.READ ( lob_loc IN BLOB, amount IN OUT NOCOPY INTEGER, offset IN INTEGER, buffer OUT RAW); DBMS_LOB.READ ( lob_loc IN CLOB CHARACTER SET ANY_CS, amount IN OUT NOCOPY INTEGER, offset IN INTEGER, buffer OUT VARCHAR2 CHARACTER SET lob_loc%CHARSET); DBMS_LOB.READ ( file_loc IN BFILE, amount IN OUT NOCOPY INTEGER, offset IN INTEGER, buffer OUT RAW);
パラメータ
表97-82 READプロシージャのパラメータ
パラメータ | 説明 |
---|---|
|
読み込むLOBのロケータ。詳細は、「操作上のノート」を参照してください。 |
|
検査するLOBのファイル・ロケータ。 |
|
読み込む、または読み込まれたバイト数( |
|
LOBの先頭からのオフセット(起点: 1)。 |
|
読取り操作用の出力バッファ。 |
例外
表97-83に、すべてのLOBインスタンスに該当する例外を示します。表97-84に、BFILE
のみに該当する例外を示します。
表97-83 READプロシージャの例外
例外 | 説明 |
---|---|
|
|
|
次のいずれかです。 - - - - - |
|
LOBの終わりに達し、LOBから読み込むバイトまたは文字がありません。 |
表97-84 BFILEに関するREADプロシージャの例外
例外 | 説明 |
---|---|
|
ファイルが入力ロケータを使用してオープンされていません。 |
|
ディレクトリが存在しません。 |
|
ディレクトリに対する権限がありません。 |
|
ディレクトリがファイルのオープン後に無効となりました。 |
|
ファイルが存在しないか、またはファイルのアクセス権限がありません。 |
使用上のノート
-
VARCHAR2
バッファの形式は、CLOB
パラメータの形式と一致する必要があります。つまり、入力LOBのパラメータのタイプがNCLOB
の場合、バッファにはNCHAR
データが含まれる必要があります。これに対して、入力LOBのパラメータのタイプがCLOB
の場合、バッファにはCHAR
データが含まれる必要があります。 -
クライアントから
DBMS_LOB
.READ
をコールすると(SQL*Plus内からのBEGIN
/END
ブロックでのコールなど)、戻されるバッファにはクライアントの文字セットのデータが含まれます。データベースは、バッファをユーザーに戻す前に、サーバーの文字セットからクライアントの文字セットにLOB値を変換します。 -
READは、読取り前に必要に応じてLOBを取得します。
-
LOBがDBFSリンクの場合、データは、可能な場合はDBFSからストリーミングされ、可能でない場合は例外が発生します。
参照:
このプロシージャの使用方法の詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください。
97.8.41 SET_DBFS_LINKプロシージャ
このファンクションは、指定したSecureFileを指定したパス名にリンクします。データはパスにコピーされません。
構文
DBMS_LOB.SET_DBFS_LINK ( lob_loc IN OUT BLOB, archive_id IN RAW(1024)); DBMS_LOB.SET_DBFS_LINK( lob_loc_dst IN OUT CLOB CHARACTER SET ANY_CS, archive_id IN RAW(1024));
パラメータ
表97-85 SET_DBFS_LINKプロシージャのパラメータ
パラメータ | 説明 |
---|---|
|
参照値を格納するLOB。 |
|
いずれかのGET_DBFS_LINKファンクションをコールすると戻されるアーカイブID。 |
例外
表97-86 SET_DBFS_LINKプロシージャの例外
例外 | 説明 |
---|---|
|
|
97.8.42 SETCONTENTTYPEプロシージャ
このプロシージャは、LOB内のデータのコンテンツ・タイプ文字列値を設定します。
構文
DBMS_LOB.SETCONTENTTYPE ( lob_loc IN OUT NOCOPY BLOB, contenttype IN VARCHAR2); DBMS_LOB.SETCONTENTTYPE ( lob_loc IN OUT NOCOPY CLOB CHARACTER SET ANY_CS, contenttype IN VARCHAR2);
パラメータ
表97-87 SETCONTENTTYPEプロシージャのパラメータ
パラメータ | 説明 |
---|---|
|
コンテンツ・タイプを割り当てるLOB。 |
|
割り当てる文字列。 |
例外
表97-88 SETCONTENTTYPEプロシージャの例外
例外 | 説明 |
---|---|
|
|
使用上のノート
SECUREFILE
に関連付けられている既存のコンテンツ・タイプをクリアするには、contenttype
を空の文字列に設定してSETCONTENTTYPE
を起動します。
97.8.43 SETOPTIONSプロシージャ
このプロシージャは、デフォルトのLOB列の設定を上書きする、圧縮および重複除外をLOBごとに有効化または無効化します。
構文
DBMS_LOB.SETOPTIONS ( lob_loc IN BLOB, option_types IN PLS_INTEGER, options IN PLS_INTEGER); DBMS_LOB.SETOPTIONS ( lob_loc IN CLOB CHARACTER SET ANY_CS, option_types IN PLS_INTEGER, options IN PLS_INTEGER);
パラメータ
例外
表97-90 SETOPTIONSプロシージャの例外
例外 | 説明 |
---|---|
|
操作に対してサポートされていないオブジェクト・タイプ。 |
|
パラメータ値が無効でした。 |
|
問合せ時に操作を実行できません。 |
使用上のノート
-
DBMS_LOB.SETOPTIONS
を使用して、個々のLOBに対する暗号化を使用可能または使用禁止にすることはできません。 -
表の作成時に圧縮または重複除外の機能が設定されていない場合、これらの機能をSecureFile列に対してオンまたはオフにすることはできません。
GETOPTIONSファンクションと
SETOPTIONS
プロシージャは、個々のSecureFileに対して動作します。特定のSecureFile LOBに対する圧縮または重複除外をオフにしたり、SETOPTIONS
によってすでにオフにされている場合はオンにすることができます。 -
このコールでは、変更を永続化させる際にサーバーへのラウンドトリップが発生します。
97.8.44 SUBSTRファンクション
このファンクションは、LOBの先頭からの絶対offset
から開始し、LOBのamount
バイトまたは文字を戻します。
固定幅のn
バイトのCLOB
の場合、SUBSTR
に対する入力amountの指定が(32767/n
)を超えると、SUBSTR
では、(32767/n
)の長さの文字バッファまたはCLOB
の長さのうち、いずれか小さい方を戻します。可変幅文字セットのCLOBの場合、n
はCLOBの文字に使用される最大バイト幅です。
構文
DBMS_LOB.SUBSTR ( lob_loc IN BLOB, amount IN INTEGER := 32767, offset IN INTEGER := 1) RETURN RAW; DBMS_LOB.SUBSTR ( lob_loc IN CLOB CHARACTER SET ANY_CS, amount IN INTEGER := 32767, offset IN INTEGER := 1) RETURN VARCHAR2 CHARACTER SET lob_loc%CHARSET; DBMS_LOB.SUBSTR ( file_loc IN BFILE, amount IN INTEGER := 32767, offset IN INTEGER := 1) RETURN RAW;
プラグマ
pragma restrict_references(SUBSTR, WNDS, WNPS, RNDS, RNPS);
パラメータ
表97-91 SUBSTRファンクションのパラメータ
パラメータ | 説明 |
---|---|
|
読み込むLOBのロケータ。詳細は、「操作上のノート」を参照してください。 |
|
検査するLOBのファイル・ロケータ。 |
|
読み込むバイト数( |
|
LOBの先頭からのオフセット(起点: 1)。 |
戻り値
表97-92 SUBSTRファンクションの戻り値
戻り値 | 説明 |
---|---|
|
ファンクション・オーバーロード。パラメータに |
|
|
|
次のいずれかです。 - 入力パラメータのいずれかが - - - - |
例外
表97-93 BFILE操作に関するSUBSTRファンクションの例外
例外 | 説明 |
---|---|
|
ファイルが入力ロケータを使用してオープンされていません。 |
|
ディレクトリが存在しません。 |
|
ディレクトリに対する権限がありません。 |
|
ディレクトリがファイルのオープン後に無効となりました。 |
|
ファイルが存在しないか、またはファイルのアクセス権限がありません。 |
使用上のノート
-
VARCHAR2
バッファの形式は、CLOB
パラメータの形式と一致する必要があります。つまり、入力LOBのパラメータのタイプがNCLOB
の場合、バッファにはNCHAR
データが含まれる必要があります。これに対して、入力LOBのパラメータのタイプがCLOB
の場合、バッファにはCHAR
データが含まれる必要があります。 -
クライアントから
DBMS_LOB
.SUBSTR
をコールすると(SQL*Plus内からのBEGIN
/END
ブロックでのコールなど)、戻されるバッファにはクライアントの文字セットのデータが含まれます。データベースは、バッファをユーザーに戻す前に、サーバーの文字セットからクライアントの文字セットにLOB値を変換します。 -
DBMS_LOB.SUBSTR
は、LOBに格納されている文字に基づいて8191個以上の文字を戻します。使用可能なバッファを超える文字バイト数が原因ですべての文字が戻されない場合、新しいオフセットでDBMS_LOB.SUBSTR
をコールして残りの文字を読み取るか、すべてのデータを抽出するまでサブプログラムのコールをループする必要があります。 -
SUBSTR
は、読取り前に必要に応じてLOBを取得します。 -
LOBがDBFSリンクの場合、データは、可能な場合はDBFSからストリーミングされ、可能でない場合は例外が発生します。
参照:
-
このプロシージャの使用方法の詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください。
97.8.45 TRIMプロシージャ
このプロシージャは、内部LOBの値をnewlen
パラメータで指定された長さに切り捨てます。
BLOB
の場合はバイト数、CLOB
の場合は文字数で長さを指定します。
ノート:
TRIM
プロシージャは、LOBの長さをnewlen
パラメータで指定された値に減らします。
空のLOBに対してTRIM
を実行すると、何も処理は行われず、TRIM
によってエラーは戻されません。newlen
で指定した新しい長さがLOBのサイズよりも大きい場合は、例外が発生します。
構文
DBMS_LOB.TRIM ( lob_loc IN OUT NOCOPY BLOB, newlen IN INTEGER); DBMS_LOB.TRIM ( lob_loc IN OUT NOCOPY CLOB CHARACTER SET ANY_CS, newlen IN INTEGER);
パラメータ
表97-94 TRIMプロシージャのパラメータ
パラメータ | 説明 |
---|---|
|
長さを切り捨てる内部LOBのロケータ。詳細は、「操作上のノート」を参照してください。 |
|
切り捨て後の新しいLOB値の長さ。 |
例外
表97-95 TRIMプロシージャの例外
例外 | 説明 |
---|---|
|
|
|
次のいずれかです。 - - |
|
問合せまたはPDMLパラレル実行サーバー内でLOB書込みが実行できません。 |
使用上のノート
-
オープン/クローズ・インタフェース内のLOB操作のラップは必須ではありません。操作を実行する前にLOBをオープンしなかった場合、LOB列のファンクション索引およびドメイン索引は、コール中に更新されます。ただし、操作を実行する前にLOBをオープンした場合は、トランザクションのコミットを実行する前にクローズする必要があります。内部LOBがクローズされるときに、
LOB
列のファンクション索引およびドメイン索引が更新されます。 -
オープン/クローズAPI内のLOB操作をラップしなかった場合、ファンクション索引およびドメイン索引はLOBへ書き込むたびに更新されます。これにより、パフォーマンスに悪影響を及ぼす可能性があります。したがって、LOBへの書込み操作を
OPEN
またはCLOSE
文の中に囲むことをお薦めします。 -
TRIM
は、LOBの長さを変更する前に、必要に応じてLOBを取得します。ただし、指定する新しい長さが0(ゼロ)の場合を除きます。
参照:
-
このプロシージャの使用方法の詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください。
97.8.46 WRITEプロシージャ
このプロシージャは、LOBの先頭からの絶対オフセットから開始し、指定された量のデータを内部LOBに書き込みます。データは、buffer
パラメータから書き込まれます。
WRITE
は、オフセット位置以降LOBにすでに存在しているデータを、指定した長さだけ置換(上書き)します。
構文
DBMS_LOB.WRITE ( lob_loc IN OUT NOCOPY BLOB, amount IN INTEGER, offset IN INTEGER, buffer IN RAW); DBMS_LOB.WRITE ( lob_loc IN OUT NOCOPY CLOB CHARACTER SET ANY_CS, amount IN INTEGER, offset IN INTEGER, buffer IN VARCHAR2 CHARACTER SET lob_loc%CHARSET);
パラメータ
表97-96 WRITEプロシージャのパラメータ
パラメータ | 説明 |
---|---|
|
書込み先の内部LOBのロケータ。詳細は、「操作上のノート」を参照してください。 |
|
書き込むバイト数( |
|
LOBの先頭からの書込み操作のオフセット(起点: 1)。 |
|
書込み用の入力バッファ。 |
例外
表97-97 WRITEプロシージャの例外
例外 | 説明 |
---|---|
|
|
|
次のいずれかです。 - - - - |
|
問合せまたはPDMLパラレル実行サーバー内で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全体を上書きするように指定されている場合を除きます。
参照:
-
このプロシージャの使用方法の詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください。
97.8.47 WRITEAPPENDプロシージャ
このプロシージャは、指定された量のデータを内部LOBの後ろに書き込みます。データは、buffer
パラメータから書き込まれます。
構文
DBMS_LOB.WRITEAPPEND ( lob_loc IN OUT NOCOPY BLOB, amount IN INTEGER, buffer IN RAW); DBMS_LOB.WRITEAPPEND ( lob_loc IN OUT NOCOPY CLOB CHARACTER SET ANY_CS, amount IN INTEGER, buffer IN VARCHAR2 CHARACTER SET lob_loc%CHARSET);
パラメータ
表97-98 WRITEAPPENDプロシージャのパラメータ
パラメータ | 説明 |
---|---|
|
書込み先の内部LOBのロケータ。詳細は、「操作上のノート」を参照してください。 |
|
書き込むバイト数( |
|
書込み用の入力バッファ。 |
使用上のノート
入力amountがバッファのデータより多い場合はエラーが発生します。入力amountがバッファのデータより少ない場合は、バッファからその量のバイト数または文字数のみLOBの後ろに書き込まれます。
例外
表97-99 WRITEAPPENDプロシージャの例外
例外 | 説明 |
---|---|
|
|
|
次のいずれかです。 - - |
|
問合せまたはPDMLパラレル実行サーバー内で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を取得します。
参照:
-
このプロシージャの使用方法の詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください。