DBMS_LOB
パッケージは、BLOB、CLOB、およびNCLOBを操作するためのサブプログラムを提供します。DBMS_LOB
を使用すると、LOBの特定の部分またはLOB全体に対するアクセスおよび操作ができます。
この章の内容は次のとおりです。
概要
セキュリティ・モデル
定数
データ・タイプ
ルールおよび制限
使用上の注意
例外
『Oracle TimesTen In-Memory Database PL/SQL開発者ガイド』のラージ・オブジェクト(LOB)に関する説明も参照してください。
DBMS_LOB
では、BLOB、CLOBおよびNCLOBの読取り、操作および変更ができます。
LOBの概要は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』のラージ・オブジェクトの概要に関する項を参照してください。
このパッケージが提供する操作は、パッケージ所有者SYS
ではなく、現行のコール・ユーザーのもとで実行されます。
無名PL/SQLブロックからコールされたDBMS_LOB
サブプログラムは、カレント・ユーザーの権限を使用して実行されます。ストアド・プロシージャからコールされたDBMS_LOB
サブプログラムは、そのストアド・プロシージャの所有者の権限を使用して実行されます。
ユーザーはプロシージャの作成時に、AUTHID
を設定して定義者の権限または実行者の権限のどちらを使用するのかを指示できます。次に例を示します。
CREATE PROCEDURE proc1 AUTHID DEFINER ...
または
CREATE PROCEDURE proc1 AUTHID CURRENT_USER ...
AUTHID
については、『Oracle TimesTen In-Memory Database PL/SQL開発者ガイド』の定義者の権限および実行者の権限に関する説明を参照してください。一時LOBに関係するセキュリティ・モデルについては「使用上の注意」を参照してください。
DBMS_LOB
パッケージでは、表2-1に示す定数が使用されます。
表2-1 DBMS_LOBの定数
定数 | タイプ | 値 | 説明 |
---|---|---|---|
|
|
12 |
コール継続時間を含む一時LOBを作成します。 |
|
|
0 |
これがデフォルトのキャラクタ・セットIDです。 |
|
|
0 |
これがデフォルトの言語コンテキストです。 |
|
|
0 |
指定したLOBを読取り専用モードでオープンします。 |
|
|
1 |
指定したLOBを読取り/書取りモードでオープンします。 |
|
|
16777216(16 MB) |
BLOBの最大サイズをバイトで設定します。 |
|
|
4194304(4 MB) |
CLOBの最大サイズをバイトで設定します。 |
|
|
0 |
成功し、警告メッセージがないことを示します。 |
|
|
10 |
セッション継続時間を含む一時LOBを作成します。 注意: TimesTenでは、トランザクションの終了時にLOBの継続時間は終了します。対応するロケータがトランザクションの終了時に無効になっている場合、一時LOBのコンテンツは破棄されます。 |
|
|
11 |
トランザクション継続時間を含む一時LOBを作成します。 |
|
|
1 |
変換できない文字があることを示すために変換ファンクションで使用されます。 |
注意:
|
DBMS_LOB
パッケージでは、表2-2に示すデータ・タイプが使用されます。
表2-2 DBMS_LOBが使用するデータ・タイプ
タイプ | 説明 |
---|---|
|
ソースまたは宛先のバイナリLOB |
|
ソースまたは宛先の |
|
ソースまたは宛先の文字LOB(NCLOBを含む) |
|
ソースまたは宛先の文字バッファ(CLOBおよびNCLOBで使用) |
|
バッファまたはLOBのサイズ、LOBへのオフセットまたはアクセス量(BLOBの場合はバイト数、CLOBまたはNCLOBの場合は文字数) |
DBMS_LOB
パッケージは特別なタイプを定義しません。
NCLOBは、固定幅および可変幅のマルチバイト各国語キャラクタ・セットを格納するためのCLOBです。
CLOB用のDBMS_LOB
サブプログラムの仕様部にある句ANY_CS
を使用すると、CLOB
タイプでCLOB
またはNCLOB
ロケータ変数を入力として受け入れることができます。
このパッケージにあるサブプログラムの仕様部に適用される規則は次のとおりです。
BLOBを操作するサブプログラムのnewlen
、offset
およびamount
パラメータを指定する際には、単位にバイトを使用する必要があります。
CLOBを操作するサブプログラムのnewlen
、offset
およびamount
パラメータを指定する際には、単位に文字を使用する必要があります。
パラメータ値の指定時に次の制限事項に従わなかった場合(またはパラメータ値を指定しなかった場合)は、INVALID_ARGVAL
例外が発生します。
LOBデータの開始位置からは、正の絶対オフセットのみが許可されています。LOBの終了位置からは、負のオフセットは許可されていません。
amount
、offset
、newlen
、nth
など、サイズおよび位置を表すパラメータには、0(ゼロ)以外の正の値のみ許可されています。SQL文字列ファンクションおよび演算子で確認される負のオフセットおよび範囲は許可されていません。
offset
、amount
、newlen
およびnth
値は、いずれのDBMS_LOB
サブプログラムの場合でも、BLOBの場合はBLOBMAXSIZE
値を、CLOBまたはNCLOBの場合はCLOBMAXSIZE
値を超えないようにする必要があります。TimesTenでは、BLOBの最大サイズは16 MBで、CLOBまたはNCLOBの最大サイズは4 MBです。
固定幅のマルチバイト・キャラクタで構成されるCLOBの場合、これらのパラメータの最大値は(CLOBMAXSIZE
/character_width_in_bytes
)文字を超えないようにする必要があります。
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
バッファの形式は文字LOBパラメータの形式に適したものである必要があります。指定したLOBがNCLOB
のタイプである場合、バッファにはNCHAR
データが含まれる必要があります。指定したLOBがCLOB
のタイプである場合、バッファにはCHAR
データが含まれる必要があります。
2つのキャラクタLOBパラメータをとるDBMS_LOB
サブプログラムの場合は、2つのパラメータは同じ形式である必要があります。つまり、両方ともNCLOBであるか、またはCLOBである必要があります。
amount
にoffset
を加えた値がデータベースで許可されているLOBの最大サイズを超えると、アクセス例外が発生します。TimesTenでは、BLOBの最大サイズは16 MBで、CLOBまたはNCLOBの最大サイズは4 MBです。
この入力条件のもとでは、READ
、COMPARE
、INSTR
、SUBSTR
などのサブプログラムでは、LOBの終了に達するまで読み込まれます。たとえば、BLOBのREAD
操作で、4 MBのサイズのLOBにユーザーが3 MBのoffset
値と2 MBのamount値を指定すると、READ
は1 MBのみを戻します(4 MB引く3 MB)。
パラメータにNULL
または無効な値が入力されると、ファンクションはNULL
を戻します。宛先LOBのパラメータにNULL
値が指定されると、プロシージャでは例外が発生します。
パラメータとしてパターンが含まれている操作(COMPARE
、INSTR
およびSUBSTR
など)では、pattern
パラメータまたは副文字列に、正規表現または特殊一致文字(SQLのLIKE
演算子の%
など)はサポートされていません。
LOBの終了条件は、READ
プロシージャでNO_DATA_FOUND
例外を使用して示されます。この例外が発生するのは、ユーザーがLOBの終了位置を超えてデータを読み込もうとしたときのみです。最後に読み込んだREAD
バッファは0(ゼロ)バイトです。
別途記載がある場合を除き、offset
パラメータのデフォルト値はBLOBデータの最初のバイト、またはCLOBまたはNCLOBデータの最初の文字を示す1です。amount
パラメータにはデフォルト値の指定はありません。これらの値は明示的に入力する必要があります。
LOBを変更する任意のサブプログラム(例: APPEND
、COPY
、ERASE
、TRIM
またはWRITE
)をコールする前に、宛先LOBが含まれている行をロックする必要があります。これらのサブプログラムでは、LOBを含んだ行のロックは暗黙的には行われません。
TimesTenでのLOBの最大サイズは、BLOBでは16 MBで、CLOBまたはNCLOBでは4 MBです。
最大バッファ・サイズは32767バイトです。
バッファ・サイズをバイトで表現するBLOBでは、バイト数の上限は32767です。
バッファ・サイズを文字で表現するCLOBまたはNCLOBでは、文字数によるバッファの上限は32767バイトです。たとえば、固定幅の2バイト文字を使用する場合、(20000*2 = 40000は32767より大きいため)20000文字はエラーになります。
DBMS_LOB
サブプログラムはLOBロケータに基づいて動作します。DBMS_LOB
サブプログラムを正常に実行するには、データベース表領域にすでに存在しているLOB(一時LOB(下部で説明)または永続LOB)を示す入力ロケータを用意する必要があります。
重要:
|
データベースでLOBを使用するには、最初にSQLデータ定義言語(DDL)を使用して、BLOB
、CLOB
またはNCLOB
タイプの列が含まれる表を定義する必要があります。
TimesTenでは、LOB内にデータを書き込むには以前のデータを上書きする必要があります。LOB内にデータを挿入し、その位置からLOBの終了の方向に以前のデータを移動する機能はありません。同様に、TimesTenでLOB内のデータを削除するは、以前のデータをゼロまたはnullデータで上書きする必要があります。LOB内のデータを削除し、その位置からLOBの開始方向に以前のデータを移動する機能はありません。いずれの場合も、(指定したオフセット位置からのLOB内の空き領域が、書き込むデータよりも少量の場合を除き、)TimesTenではLOBのサイズは変更されません(Oracle Databaseでは、DBMS_LOB
FRAGMENT
プロシージャを使用し、データを挿入または削除したり、他のデータの移動することによって、LOBのサイズを変更できます。TimesTenではこれらのプロシージャはサポートされていません)。
DBMS_LOB
のプロシージャおよびファンクションは、TimesTenのLOBおよびパススルーLOB(TimesTenを介してアクセスする、TimesTenのLOBとして公開されるOracle DatabaseのLOB)の両方でサポートされています。ただし、TimesTenでは、CREATETEMPORARY
は一時LOBの作成のためのみに使用できることに注意する必要があります。一時パススルーLOBがSQLなどその他のメカニズムで作成されている場合、そのLOBでISTEMPORARY
およびFREETEMPORARY
を使用することは可能です。
TimesTenでは、特にBFILEを対象としたDBMS_LOB
サブプログラム、SecureFiles(Database File System機能を含む)、またはLOB内部でのデータ・フラグメントの挿入または削除(FRAGMENT
サブプログラム)はサポートしていません。
この後の項では、次の項目について説明します。
表にBLOB
、CLOB
またはNCLOB
列を定義した後、データベース表にLOBを移入するには、SQLデータ操作言語(DML)を使用して、LOB列のロケータを初期化するか、または移入します。
TimesTenでは、一時LOBの定義、作成、削除、アクセスおよび更新がサポートされています。一時LOBのデータは、一時データ・パーティションに格納されます。一時LOBはデータベースに永続的には格納されません。この目的は、主にアプリケーションからLOBデータを変換することです。
一時LOB(BLOB、CLOBまたはNCLOB)は、PL/SQLを使用して作成または操作できます。
一時LOBは、作成されたときは空の状態です。TimesTenで一時LOBは、それが作成されたトランザクションが終了するとすべて削除されます。また、処理が途中で停止したり、データベースがクラッシュした場合、一時LOBは削除され、その領域は解放されます。
一時LOBに関する読取り一貫性、取消し、バックアップ、パラレル処理またはトランザクション管理はサポートされていません。一時LOBでは、読取り一貫性およびロールバックがサポートされていないため、エラーが発生した場合、ユーザーは一時LOBを解放して、最初から操作をやり直す必要があります。
PL/SQLでは、一時LOBに対して複数のロケータは使用しないでください。読取り一貫性、取消しおよびバージョンが、一時LOBに対しては生成されないため、同じ一時LOBに複数のロケータを割り当てると、パフォーマンスに影響する可能性があります。具体的には、各ロケータが一時LOBの独自のコピーを所有するためです。一時LOBロケータは、必要に応じて、参照によって別のプロシージャに渡されます。
他のロケータが一時LOBをポイントしているときにユーザーがその一時LOBを変更すると、一時LOBのコピーが作成されます。すると、変更が実行されたロケータは、一時LOBの新しいコピーをポイントするようになります。変更が行われたロケータと同様、他のロケータもそれ以降同じデータを参照しなくなります。このような状況では、読取り一貫性スナップショットおよびバージョン・ページによって、ユーザーは独自のバージョンのLOBを簡単に参照できるため、永続LOBではディープ・コピーは生成されません。
一時LOBは表スキーマと関連付けられていないため、行内および行外の一時LOBという概念はありません。ユーザーが一時LOBインスタンスを作成すると、エンジンによってLOBデータへのロケータが作成され戻されます。PL/SQLのDBMS_LOB
パッケージおよびその他のプログラム・インタフェースは、このロケータを介して、永続LOBに対する操作と同様に一時LOBを操作します。
クライアント側の一時LOBという概念はありません。一時LOBはすべてサーバーに常駐します。
一時LOBのインスタンスは、永続LOBと同様の、適切なDBMS_LOB
ファンクションおよびプロシージャを使用してアクセスおよび変更できます。一時LOBを永続化するには、COPY
プロシージャを使用し、それをデータベース内の(適切な)BLOB
、CLOB
またはNCLOB
列にコピーします。
一時LOBインスタンスを終了したら、FREETEMPORARY
プロシージャを使用してそれを解放します。
セキュリティは、LOBロケータを介して提供されます。一時LOBは、その作成ユーザーのみ参照できます。ロケータは、あるユーザーのセッションから別のユーザーのセッションに渡すことはできません。あるセッションから別のセッションにロケータを渡しても、元のセッションの一時LOBにはアクセスできません。
一時LOBに固有の注意事項は次のとおりです。
NULL
のパラメータがある場合、DBMS_LOB
のどのファンクションでもNULL
が戻されます。LOBロケータがNULL
として入力されると、DBMS_LOB
のすべてのプロシージャで例外が発生します。
CLOBに基づく操作では、パラメータ(CLOB
パラメータやVARCHAR2
のバッファやパターンなど)のキャラクタ・セットID(CSID)が一致しているかどうかは検証されません。この確認はユーザーが各自で行ってください。
表2-3 DBMS_LOBの例外
例外 | コード | 説明 |
---|---|---|
|
|
LOBに書き込もうとしているデータ量が多すぎます。TimesTenでは、BLOBのサイズは16 MBに、CLOBまたはNCLOBのサイズは4 MBに制限されています。 |
|
|
LOBバッファを有効にした状態では操作を実行できません。 |
|
|
|
|
|
|
|
|
引数はNULL以外の有効な値である必要がありますが、転送された引数値は |
|
|
これは、ループ読取り操作でLOBの終了を示すインジケータです。ハード・エラーではありません。 |
|
|
問合せ内でLOB書込みを実行できません(これはTimesTenでは実行できません。) |
|
|
これは、サブプログラムのパラメータ値が無効なためのPL/SQLエラーです。 |
注意: DBMS_LOB サブプログラムの「例外」の項で説明するとおり、LOBバッファリングが有効の場合は動作しないサブプログラムがいくつかあります。(LOBバッファリングとは、たとえばOCIなどを介して有効にできる機能です。『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』のLOBバッファリング・サブシステムに関する説明を参照してください。 |
表2-4 DBMS_LOBのサブプログラム
サブプログラム | 説明 |
---|---|
|
ソースLOBの内容を宛先LOBに追加します。 |
|
オープンされているLOBをクローズします。 |
|
2つのLOB全体、または2つのLOBの一部を比較します。 |
|
ソースCLOBまたはNCLOBから文字データを読み取り、文字データを指定したキャラクタ・セットに変換して、変換したデータをバイナリ形式で宛先BLOBに書き込み、新しいオフセットを戻します。 |
|
ソースBLOBを取得し、指定したキャラクタ・セットを使用して、ソースのバイナリ・データを文字データに変換し、文字データを宛先CLOBまたはNCLOBに書き込み、新しいオフセットを戻します。 |
|
ソースLOBの全体または一部を宛先LOBにコピーします。 |
|
一時データ・パーティションに一時LOBを作成します。 |
|
LOBの全体または一部を消去します。 |
|
一時データ・パーティションの一時LOBを解放します。 |
|
LOB値を格納するLOBチャンクの使用領域容量を戻します。 |
|
LOB値の長さを、BLOBの場合はバイト数で、CLOBの場合は文字数で戻します。 |
|
指定したLOBのLOBタイプの格納の上限を戻します。 |
|
LOBにおけるパターンの |
|
LOBが入力ロケータを使用して、すでにオープンされたかどうかをチェックします。 |
|
ロケータが一時LOBをポイントしているかどうかをチェックします。 |
|
LOB(永続または一時)を、指定された読取り/書込みまたは読取り専用モードでオープンします。 |
|
指定されたオフセットからLOBのデータを読み取ります。 |
|
指定されたオフセットからLOB値の一部を戻します。 |
|
指定された長さまでLOB値を切り捨てます。 |
|
指定されたオフセットからLOBにデータを書き込みます。 |
|
バッファをLOBの終了に追加します。 |
このプロシージャでは、ソースLOBの内容を宛先LOBに追加します。ソースLOBを完全に追加します(WRITEAPPEND
プロシージャとは混同しないでください。)
構文
DBMS_LOB.APPEND ( dest_lob IN OUT NOCOPY BLOB, src_lob IN BLOB); DBMS_LOB.APPEND ( dest_lob IN OUT NOCOPY CLOB CHARACTER SET ANY_CS, src_lob IN CLOB CHARACTER SET dest_lob%CHARSET);
パラメータ
使用上の注意
LOBへの書込み操作は、OPEN
およびCLOSE
コールで囲むことをお薦めします(必須ではありません)。ただし、操作を実行する前にLOBをオープンした場合は、トランザクションのコミットまたはロールバックを実行する前にクローズする必要があります。
例外
表2-6 APPENDプロシージャの例外
例外 | 説明 |
---|---|
|
ソースまたは宛先LOBのいずれかが |
|
問合せ内でLOB書込みを実行できません(これはTimesTenでは実行できません。) |
|
いずれかのLOBでLOBバッファを有効にした状態では操作を実行できません。 |
例
ここでは、APPEND
プロシージャの使用例を示します。
create table t1 (a int, c clob); insert into t1(a,c) values(1, 'abcde'); 1 row inserted. commit; declare c1 clob; c2 clob; begin c1 := 'abc'; select c into c2 from t1 where a = 1; dbms_output.put_line('c1 before append is ' || c1); dbms_output.put_line('c2 before append is ' || c2); dbms_lob.append(c1, c2); dbms_output.put_line('c1 after append is ' || c1); dbms_output.put_line('c2 after append is ' || c2); insert into t1 values (2, c1); end; c1 before append is abc c2 before append is abcde c1 after append is abcabcde c2 after append is abcde PL/SQL procedure successfully completed. select * from t1; < 1, abcde > < 2, abcabcde > 2 rows found.
(SQLスクリプトからコマンドを実行した後、出力が表示されます。)
このプロシージャでは、すでにオープンされているLOBをクローズします。
構文
DBMS_LOB.CLOSE ( lob_loc IN OUT NOCOPY BLOB); DBMS_LOB.CLOSE ( lob_loc IN OUT NOCOPY CLOB CHARACTER SET ANY_CS);
パラメータ
使用上の注意
CLOSE
では、サーバーへのラウンドトリップが必要になります。
LOB操作はOPEN
およびCLOSE
コールで囲む必要はありません。ただし、LOBをオープンしている場合は、トランザクションをコミットまたはロールバックする前にクローズする必要があります。
トランザクションによってオープンされたすべてのLOBをクローズする前にトランザクションをコミットすると、エラーが発生します。エラーが戻された場合、LOBのオープンのステータスは廃棄されますが、トランザクションのコミットは正常に行われます。したがって、LOBおよび非LOBデータに対するすべての変更トランザクションはコミットされます。
例外
エラーは、LOBがオープンしていない場合に戻されます。
このファンクションは、2つのLOB全体、または2つのLOBの一部を比較します。
構文
DBMS_LOB.COMPARE ( lob_1 IN BLOB, lob_2 IN BLOB, amount IN INTEGER := DBMS_LOB.BLOBMAXSIZE, 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.CLOBMAXSIZE, offset_1 IN INTEGER := 1, offset_2 IN INTEGER := 1) RETURN INTEGER;
パラメータ
表2-8 COMPAREファンクション・パラメータ
パラメータ | 説明 |
---|---|
|
比較する1番目のLOBのロケータ |
|
比較する2番目のLOBのロケータ |
|
比較するバイト数(BLOBの場合)または文字数(CLOBまたはNCLOB) |
|
1番目のLOBのバイト数または文字数でのオフセット(起点: 1) |
|
2番目のLOBのバイト数または文字数でのオフセット(起点: 1) |
戻り値
このファンクションは、次のいずれかを戻します。
データが指定の範囲と正確に一致する場合は0(ゼロ)
1番目のLOBが2番目のLOBより小さい場合は-1
1番目のLOBが2番目のLOBより大きい場合は1
amount
、offset_1
またはoffset_2
の値が、1からBLOBMAXSIZE
またはCLOBMAXSIZE
(の適切な方)の範囲外で無効な場合はNULL
使用上の注意
同じタイプのLOBのみ比較できます。たとえば、CLOBとBLOBを比較することはできません。
固定幅のn
バイトのCLOBまたはNCLOBの場合は、COMPARE
に対する入力amountの指定がCLOBMAXSIZE/
n
を超えると、COMPARE
は、CLOBMAXSIZE/
n
またはMax(length(clob1), length(clob2))
のうち、小さい方の範囲で文字と一致します。
このプロシージャは、ソースCLOBまたはNCLOBから、文字データを読み取り、文字データを指定したキャラクタ・セットに変換して、変換したデータをバイナリ形式で宛先BLOBに書き込み、新しいオフセットを戻します。このプロシージャは、永続LOBまたは一時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);
パラメータ
表2-9 CONVERTTOBLOBプロシージャ・パラメータ
パラメータ | 説明 |
---|---|
|
宛先LOBのロケータ |
|
ソースLOBのロケータ |
|
ソースLOBから変換する文字数 CLOBまたはNCLOB全体を変換する場合、定数 |
|
LOBの先頭から開始するには1の値を指定します。 ( |
|
( ( |
|
変換BLOBデータのキャラクタ・セットID |
|
( ( このパラメータは、TimesTenではサポートされていません。 |
|
警告メッセージ このパラメータは、TimesTenではサポートされていません。 |
使用上の注意
事前条件
CONVERTTOBLOB
をコールする前に、次の事前条件を満たしている必要があります。
ソースと宛先の両方のLOBが存在している。
宛先LOBが永続LOBの場合、行がロックされている。行をロックするには、SELECT
文のFOR
UPDATE
句を使用して、LOBを選択します。
定数およびデフォルト
すべてのパラメータが必要です。各OUT
またはIN OUT
パラメータに変数を渡す必要があります。各IN
パラメータに変数または値を渡す必要があります。
表2-10に各パラメータの一般的な値の要約を示します。値によっては定数が使用されるので注意してください。このような定数は、dbmslob.sql
パッケージ仕様部ファイルに定義されています。
表2-10 CONVERTTOBLOBの一般的な値
パラメータ | 値 | 説明 |
---|---|---|
|
|
LOB全体を変換します。 |
|
|
先頭から開始します。 |
|
|
先頭から開始します。 |
|
|
デフォルトのキャラクタ・セットID(ソースCLOBと同じIDを使用します)。 |
|
|
これがデフォルトの言語コンテキストです(TimesTenでは無視されます)。 |
|
|
これは警告メッセージです(TimesTenでは無視されます)。 |
一般的な注意
blob_csid
パラメータに宛先BLOBの目的のキャラクタ・セットIDを指定する必要があります。0値を渡す場合、データベースでは目的のキャラクタ・セットがソースCLOBのキャラクタ・セットと同じであると想定されます。
ソースおよび宛先の両方のLOBに対するオフセット、およびソースLOBからコピーする文字数を指定する必要があります。amount
およびsrc_offset
値は文字単位、dest_offset
はバイト単位です。LOB全体を変換するには、amount
パラメータにCLOBMAXSIZE
を指定します。
CONVERTTOBLOB
は、データの変換および書込み前に、必要に応じてソースまたは宛先LOBを取得します。
例外
表2-11 CONVERTTOBLOBプロシージャの例外
例外 | 説明 |
---|---|
|
入力パラメータのいずれかが |
|
次のいずれかが該当します。
|
このプロシージャはソースBLOBを取得し、指定したキャラクタ・セットを使用して、ソースのバイナリ・データを文字データに変換し、文字データを宛先CLOBまたはNCLOBに書き込み、新しいオフセットを戻します。このプロシージャは、永続LOBまたは一時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);
パラメータ
表2-12 CONVERTTOCLOBプロシージャ・パラメータ
パラメータ | 説明 |
---|---|
|
宛先LOBのロケータ |
|
ソースLOBのロケータ |
|
ソースLOBから変換するバイト数 BLOB全体を変換する場合、定数 |
|
( LOBの先頭から開始するには1の値を指定します。 ( このオフセットは、常に書込み終了位置の後にある最初の完全な文字をポイントします。 |
|
( ( |
|
ソースBLOBデータのキャラクタ・セットID |
|
( このパラメータは、TimesTenではサポートされていません。 |
|
警告メッセージ このパラメータは、TimesTenではサポートされていません。 |
使用上の注意
事前条件
CONVERTTOCLOB
をコールする前に、次の事前条件を満たしている必要があります。
ソースと宛先の両方のLOBが存在している。
宛先LOBが永続LOBの場合、CONVERTTOCLOB
プロシージャをコールする前に行がロックされている。行をロックするには、SELECT
文のFOR UPDATE
句を使用して、LOBを選択します。
定数およびデフォルト
すべてのパラメータが必要です。各OUT
またはIN OUT
パラメータに変数を渡す必要があります。各IN
パラメータに変数または値を渡す必要があります。
表2-13に各パラメータの一般的な値の要約を示します。値によっては定数が使用されるので注意してください。このような定数は、dbmslob.sql
パッケージ仕様部ファイルに定義されています。
表2-13 CONVERTTOCLOBの一般的な値
パラメータ | 値 | 説明 |
---|---|---|
|
|
LOB全体を変換します。 |
|
|
先頭から開始します。 |
|
|
先頭から開始します。 |
|
|
デフォルトのキャラクタ・セットID(宛先CLOBと同じIDを使用します)。 |
|
|
これがデフォルトの言語コンテキストです(TimesTenでは無視されます)。 |
|
|
これは警告メッセージです(TimesTenでは無視されます)。 |
一般的な注意
blob_csid
パラメータにソースBLOBの目的のキャラクタ・セットIDを指定する必要があります。0値を渡す場合、データベースでは目的のキャラクタ・セットが宛先CLOBのキャラクタ・セットと同じであると想定されます。
ソースおよび宛先の両方のLOBに対するオフセット、およびソースLOBからコピーする文字数を指定する必要があります。amount
およびsrc_offset
値はバイト単位でdest_offset
は文字単位です。LOB全体を変換するには、amount
パラメータにBLOBMAXSIZE
を指定します。
CONVERTTOCLOB
は、データの変換および書込み前に、必要に応じてソースまたは宛先LOBを取得します。
例外
表2-14 CONVERTTOCLOBプロシージャの例外
例外 | 説明 |
---|---|
|
入力パラメータのいずれかが |
|
次のいずれかが該当します。
|
このプロシージャでは、ソース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);
パラメータ
表2-15 COPYプロシージャ・パラメータ
パラメータ | 説明 |
---|---|
|
コピーする宛先LOBのロケータ |
|
コピー元のソースLOBのロケータ |
|
コピーするバイト数(BLOBの場合)または文字数(CLOBまたはNCLOBの場合) |
|
宛先LOBのコピー開始位置を示すオフセット(起点: 1)(バイト数または文字数で指定します) |
|
ソースLOBのコピー開始位置を示すオフセット(起点: 1)(バイト数または文字数で指定します) |
使用上の注意
宛先LOBに指定したオフセットが、現在そのLOBに格納されているデータの終わりを超えている場合は、オフセットに到達するために宛先LOBに、0(ゼロ)バイトのFILLER(BLOBの場合)または空白(CLOBまたはNCLOBの場合)が挿入されます。オフセットが宛先LOBの現行の長さより小さい場合、既存のデータは上書きされます。
ソースLOBのデータ長を超える量を指定してもエラーにはなりません。したがって、ソースLOBのデータを、src_offset
からソースLOBの終了までコピーする大量のコピーを指定できます。
LOBへの書込み操作は、OPEN
およびCLOSE
コールで囲むことをお薦めします(必須ではありません)。ただし、操作を実行する前にLOBをオープンした場合は、トランザクションのコミットまたはロールバックを実行する前にクローズする必要があります。
COPY
では、1つのTimesTen LOBから別のTimesTen LOBにコピーできるだけでなく、TimesTen LOBからパススルーLOBへ、パススルーLOBからTimesTen LOBへ、または1つのパススルーLOBから別のパススルーLOBへコピーすることができます。パススルーLOBのサイズがTimesTen LOBのサイズ制限より大きい場合、パススルーLOBをTimesTen LOBにコピーしようとするとエラーが発生します。
例外
最大LOBサイズはBLOBの場合はBLOBMAXSIZE
で、CLOBの場合はCLOBMAXSIZE
です。
表2-16 COPYプロシージャの例外
例外 | 説明 |
---|---|
|
入力パラメータのいずれかが |
|
次のいずれかが該当します。
|
|
問合せ内でLOB書込みを実行できません(これはTimesTenでは実行できません。) |
|
いずれかのLOBでLOBバッファを有効にした状態では操作を実行できません。 |
例
この項の例では、PL/SQLでLOBをコピーする方法、パススルーLOB(Oracle Databaseから)とTimesTen LOB間でLOBをコピーする方法を示します。1番目の例では、COPY
プロシージャを使用します。2番目では、DBMS_LOB
パッケージの機能も使用しますが、対照的に単純にINSERT
とUPDATE
文を使用します。
COPYプロシージャを使用したCLOBのコピー
この例では、COPY
プロシージャを使用し、Oracle DatabaseからパススルーCLOBをTimesTen CLOBにまずコピーし、TimesTen CLOBをパススルーCLOBにコピーします。
autocommit 0; passthrough 0; DROP TABLE tt_table; CREATE TABLE tt_table (i INT, c CLOB); COMMIT; passthrough 3; DROP TABLE ora_table; CREATE TABLE ora_table (i INT, c CLOB); COMMIT; passthrough 0; set serveroutput on; DECLARE passthru_clob CLOB; tt_clob CLOB; clob_length BINARY_INTEGER; clob_buffer VARCHAR2(80); BEGIN EXECUTE IMMEDIATE 'call ttoptsetflag(''passthrough'', 1)'; -- Note that in PL/SQL, passthrough statements must be executed as -- dynamic SQL, and SELECT INTO must be used to assign a passthrough LOB. -- 1. Copy a passthrough CLOB on Oracle Database to a TimesTen CLOB -- On Oracle Database : insert a row with an empty CLOB, get a passthrough CLOB -- handle, and append to the passthrough CLOB. EXECUTE IMMEDIATE 'INSERT INTO ora_table VALUES (1, EMPTY_CLOB())'; EXECUTE IMMEDIATE 'SELECT c FROM ora_table WHERE i = 1 FOR UPDATE' INTO passthru_clob; DBMS_LOB.APPEND(passthru_clob, 'Copy from Oracle Database to TimesTen'); clob_length := DBMS_LOB.GETLENGTH(passthru_clob); -- On TimesTen: insert a row with an empty CLOB, and get a TimesTen CLOB handle INSERT INTO tt_table VALUES (1, EMPTY_CLOB()) RETURNING c INTO tt_clob; -- Copy the passthrough CLOB on Oracle Database to a TimesTen CLOB DBMS_LOB.COPY(tt_clob, passthru_clob, clob_length, 1, 1); -- On TimesTen: display the modified TimesTen CLOB DBMS_LOB.READ(tt_clob, clob_length, 1, clob_buffer); DBMS_OUTPUT.PUT_LINE(clob_buffer); -- 2. Copy a TimesTen CLOB to a passthrough CLOB on Oracle Database -- On TimesTen: insert a row with LOB data, and get a TimesTen CLOB handle INSERT INTO tt_table VALUES (2, 'Copy from TimesTen to Oracle Database.') RETURNING c INTO tt_clob; clob_length := DBMS_LOB.GETLENGTH(tt_clob); -- On Oracle Database: insert a row with an empty CLOB, and get a passthrough -- CLOB handle EXECUTE IMMEDIATE 'INSERT INTO ora_table VALUES (2, EMPTY_CLOB())'; EXECUTE IMMEDIATE 'SELECT c FROM ora_table WHERE i = 2 FOR UPDATE' INTO passthru_clob ; -- Copy a TimesTen CLOB to a passthrough CLOB on Oracle Database DBMS_LOB.COPY(passthru_clob, tt_clob, clob_length, 1, 1); -- On Oracle Database: display the modified passthrough CLOB DBMS_LOB.READ(passthru_clob, clob_length, 1, clob_buffer); DBMS_OUTPUT.PUT_LINE(clob_buffer); COMMIT; EXECUTE IMMEDIATE 'call ttoptsetflag(''passthrough'', 0)'; END;
INSERTおよびUPDATE文を使用したCLOBのコピー
Oracle DatabaseからのパススルーLOBは、TimesTenの表に対して実行するINSERT
またはUPDATE
文とバインドできます。この方法で、パススルーLOBをTimesTen LOBにコピーできます。同様に、TimesTen LOBは、Oracle Databaseの表に対して実行するINSERT
またはUPDATE
文とバインドできます。この方法で、TimesTen LOBをパススルーLOBにコピーできます。
この例では、これらの両方のシナリオを示しています。
autocommit 0; passthrough 0; DROP TABLE tt_table; CREATE TABLE tt_table (i INT, c CLOB); COMMIT; passthrough 3; DROP TABLE ora_table; CREATE TABLE ora_table (i INT, c CLOB); COMMIT; passthrough 0; set serveroutput on; DECLARE passthru_clob CLOB; tt_clob CLOB; clob_length BINARY_INTEGER; clob_buffer VARCHAR2(80); BEGIN EXECUTE IMMEDIATE 'call ttoptsetflag(''passthrough'', 1)'; -- Note that in PL/SQL, passthrough statements must be executed as -- dynamic SQL, and SELECT INTO must be used to assign a passthrough LOB. -- 1. A TimesTen CLOB is updated with a passthrough CLOB on Oracle Database -- On TimesTen: insert a row with a NULL CLOB value INSERT INTO tt_table VALUES (1, NULL); -- On Oracle Database: insert a row with an empty CLOB, get a passthrough CLOB -- handle EXECUTE IMMEDIATE 'INSERT INTO ora_table VALUES (1, ''Copy from Oracle Database to TimesTen'')'; EXECUTE IMMEDIATE 'SELECT c FROM ora_table WHERE i = 1' INTO passthru_clob ; -- On TimesTen: update the TimesTen CLOB with the passthrough CLOB UPDATE tt_table SET c = passthru_clob where i = 1; -- On TimesTen: display the modified TimesTen CLOB SELECT c INTO tt_clob FROM tt_table WHERE i = 1; clob_length := DBMS_LOB.GETLENGTH(tt_clob); DBMS_LOB.READ(tt_clob, clob_length, 1, clob_buffer); DBMS_OUTPUT.PUT_LINE(clob_buffer); -- 2. A passthrough table on Oracle Database is inserted with a TimesTen CLOB -- On TimesTen: insert a row with a CLOB value, and get a TimesTen CLOB handle INSERT INTO tt_table VALUES (2, 'Copy from TimesTen to Oracle Database.') RETURNING c INTO tt_clob; -- On Oracle Database: insert a row on Oracle Database with the TimesTen CLOB EXECUTE IMMEDIATE 'INSERT INTO ora_table VALUES (2, :1)' USING tt_clob; -- On Oracle Database: display the modified passthrough CLOB EXECUTE IMMEDIATE 'SELECT c FROM ora_table WHERE i = 2' INTO passthru_clob; clob_length := DBMS_LOB.GETLENGTH(passthru_clob); DBMS_LOB.READ(passthru_clob, clob_length, 1, clob_buffer); DBMS_OUTPUT.PUT_LINE(clob_buffer); COMMIT; EXECUTE IMMEDIATE 'call ttoptsetflag(''passthrough'', 0)'; END;
このプロシージャは、一時データ・パーティションに一時BLOB、CLOBまたはNCLOBを作成します。
一時LOBの使用が終了したら、FREETEMPORARYプロシージャを使用します。
重要: TimesTenでは、一時LOBを作成すると、データベース・トランザクションがまだ進行していない場合は、データベース・トランザクションが作成されます。トランザクションを終了するには、コミットまたはロールバックを実行する必要があります。 |
構文
DBMS_LOB.CREATETEMPORARY ( lob_loc IN OUT NOCOPY BLOB, cache IN BOOLEAN, dur IN BINARY_INTEGER := DBMS_LOB.SESSION); DBMS_LOB.CREATETEMPORARY ( lob_loc IN OUT NOCOPY CLOB CHARACTER SET ANY_CS, cache IN BOOLEAN, dur IN BINARY_INTEGER := DBMS_LOB.SESSION);
パラメータ
表2-17 CREATETEMPORARYプロシージャ・パラメータ
パラメータ | 説明 |
---|---|
|
一時LOBのロケータ
|
|
LOBをバッファ・キャッシュに読み込むかどうかを示すフラグ |
|
一時LOBをいつクリーン・アップするかのヒントを指定する、 注意: いずれの設定も許可されますが、TimesTenではトランザクションが終了するとLOBロケータの継続時間が終了します。 |
使用上の注意
CREATETEMPORARY
を使用して一時パススルー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);
パラメータ
表2-18 ERASEプロシージャ・パラメータ
パラメータ | 説明 |
---|---|
|
LOBのロケータ |
|
( ( |
|
LOBの先頭からの絶対オフセット(起点: 1)(BLOBの場合はバイト数、CLOBまたはNCLOBの場合は文字数で指定します) |
使用上の注意
LOB内部からデータが消去されると、0(ゼロ)バイトのFILLER(BLOBの場合)または空白(CLOBまたはNCLOBの場合)が書き込まれます。
先にLOBデータの終わりに到達した場合、実際に消去されたバイト数または文字数は、amount
パラメータで指定した数と異なる場合があります。実際に消去された文字数またはバイト数は、amount
パラメータに戻されます。
LOBへの書込み操作は、OPEN
およびCLOSE
コールで囲むことをお薦めします(必須ではありません)。ただし、操作を実行する前にLOBをオープンした場合は、トランザクションのコミットまたはロールバックを実行する前にクローズする必要があります。
例外
最大LOBサイズはBLOBの場合はBLOBMAXSIZE
で、CLOBの場合はCLOBMAXSIZE
です。
表2-19 ERASEプロシージャの例外
例外 | 説明 |
---|---|
|
入力パラメータのいずれかが |
|
次のいずれかが該当します。
|
|
問合せ内でLOB書込みを実行できません(これはTimesTenでは実行できません。) |
|
LOBでLOBバッファを有効にした状態では操作を実行できません。 |
このプロシージャは、一時データ・パーティションの一時BLOB、CLOBまたはNCLOBを解放します。
CREATETEMPORARYプロシージャに関する説明も参照してください。
構文
DBMS_LOB.FREETEMPORARY ( lob_loc IN OUT NOCOPY BLOB); DBMS_LOB.FREETEMPORARY ( lob_loc IN OUT NOCOPY CLOB CHARACTER SET ANY_CS);
パラメータ
使用上の注意
FREETEMPORARY
へのコール後、解放されたLOBロケータには無効のマークが設定されます。
無効のLOBロケータが、PL/SQLの割当て操作によって別のLOBロケータに割り当てられている場合、割当て先も解放され、無効のマークが設定されます。
一時パススルーLOBはCREATETEMPORARY
を使用しては作成できませんが、SQLなどその他のメカニズムで作成された場合、そのLOBでISTEMPORARY
およびFREETEMPORARY
を使用できます。
TimesTenではこの機能をサポートしておらず、単純に値32Kを相互運用性のために戻します。この値は、TimesTenアプリケーションのパフォーマンスのチューニングには関係しません。(Oracle Databaseの機能については、『Oracle Database PL/SQLパッケージおよびタイプ・リファレンス』のGETCHUNKSIZEファンクションに関する説明を参照してください。)
構文
DBMS_LOB.GETCHUNKSIZE ( lob_loc IN BLOB) RETURN INTEGER; DBMS_LOB.GETCHUNKSIZE ( lob_loc IN CLOB CHARACTER SET ANY_CS) RETURN INTEGER;
パラメータ
戻り値
値32Kは戻されますが、この数値に依存してアプリケーションのパフォーマンスのチューニングはしないようにする必要があります。
例外
このファンクションでは指定したLOBの長さをバイト数(BLOBの場合)または文字数(CLOBまたはNCLOBの場合)で戻します。
構文
DBMS_LOB.GETLENGTH ( lob_loc IN BLOB) RETURN INTEGER; DBMS_LOB.GETLENGTH ( lob_loc IN CLOB CHARACTER SET ANY_CS) RETURN INTEGER;
パラメータ
戻り値
LOB値の長さを、バイト数または文字数のINTEGER
値で戻します。入力LOBまたはlob_loc
がNULL
の場合、NULL
が戻されます。
使用上の注意
以前に行ったERASE
またはWRITE
操作でLOBに挿入された0(ゼロ)バイトまたは空白のFILLERは長さに含まれます。空のLOBの長さは0(ゼロ)です。
例外
例
次の例は、GETLENGTH
ファンクションの使用方法を示します。
create table t1 (a int, b blob, c clob); insert into t1(a,b,c) values(1, 0x123451234554321, 'abcde'); 1 row inserted. commit; declare myblob blob; i integer; begin myblob := empty_blob(); i := dbms_lob.getlength(myblob); dbms_output.put_line('Length of BLOB before SELECT: ' || i); select b into myblob from t1 where a=1; i := dbms_lob.getlength(myblob); dbms_output.put_line('Length of BLOB after SELECT: ' || i); end; Length of BLOB before SELECT: 0 Length of BLOB after SELECT: 8 PL/SQL procedure successfully completed.
(SQLスクリプトからコマンドを実行した後、出力が表示されます。)
このファンクションは、指定した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;
パラメータ
戻り値
TimesTenでは、指定したLOBのタイプのバイト単位での最大の記憶域容量値が単純に戻されます。つまり、BLOBの場合は16777216(16 MB)でCLOBまたはNCLOBの場合は4194304(4 MB)です。
このファンクションは、指定したオフセットを開始位置として、指定した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;
パラメータ
表2-26 INSTRファンクション・パラメータ
パラメータ | 説明 |
---|---|
|
LOBのロケータ |
|
テストするパターン このパターンは、BLOBの場合は |
|
パターン・マッチングの開始位置を示す絶対オフセット(起点: 1)(BLOBの場合はバイト数、CLOBまたはNCLOBの場合は文字数で指定します) |
|
LOB内でパターンが何回目に出現するか(起点: 1)。 |
戻り値
このファンクションは、次のいずれかを戻します。
一致するパターンの開始位置のオフセットのINTEGER
値(BLOBの場合はバイト数、CLOBまたはNCLOBの場合は文字数で指定します)
パターンが見つからない場合は0(ゼロ)
いずれかの入力パラメータがNULL
か無効か、次のいずれかに該当する場合はNULL
offset
< 1またはoffset
>最大LOBサイズ
nth
< 1またはnth
>最大LOBサイズ
ここで、最大LOBサイズはBLOBの場合はBLOBMAXSIZE
で、CLOBの場合はCLOBMAXSIZE
です。
使用上の注意
CLOBまたはNCLOBの場合、pattern
パラメータのVARCHAR2
バッファの形式はLOBのタイプに適したものである必要があります。指定したLOBがNCLOB
のタイプである場合、パターンにはNCHAR
データが含まれる必要があります。指定したLOBがCLOB
のタイプである場合、パターンにはCHAR
データが含まれる必要があります。
INSTR
など、パターン・マッチング用にRAW
またはVARCHAR2
パラメータを受け入れる操作では、パターン・パラメータまたは副文字列において、正規表現または特殊一致文字(例: SQLのLIKE
)はサポートされていません。
このファンクションは、LOBが入力ロケータを使用してすでにオープンされているかどうかをチェックします。
構文
DBMS_LOB.ISOPEN ( lob_loc IN BLOB) RETURN INTEGER; DBMS_LOB.ISOPEN ( lob_loc IN CLOB CHARACTER SET ANY_CS) RETURN INTEGER;
パラメータ
戻り値
戻り値は、LOBがオープンしている場合は1、していない場合は0(ゼロ)です。
使用上の注意
オープンのステータスは、ロケータではなくLOBに関連付けられています。LOBのオープンにロケータが使用されている場合、LOBのその他のロケータもそれをオープンとみなします。
ISOPEN
では、LOBがオープンであるかの状態をサーバー上で調べる必要があるため、ラウンドトリップする必要があります。
このファンクションはLOBが一時的であるかどうかを判断します。
構文
DBMS_LOB.ISTEMPORARY ( lob_loc IN BLOB) RETURN INTEGER; DBMS_LOB.ISTEMPORARY ( lob_loc IN CLOB CHARACTER SET ANY_CS) RETURN INTEGER;
パラメータ
戻り値
戻り値は、LOBが存在し一時LOBである場合は1、LOBが存在しないか一時LOBではない場合は0(ゼロ)、また指定されたロケータ値がNULL
の場合はNULL
です。
使用上の注意
FREETEMPORARY
で一時LOBを解放すると、LOBロケータはNULL
に設定されません。その結果、ISTEMPORARY
では、解放されたが明示的にNULL
にリセットされていないロケータについては0 (ゼロ)を戻します。
一時パススルーLOBはCREATETEMPORARY
を使用しては作成できませんが、SQLなどその他のメカニズムで作成された場合、そのLOBでISTEMPORARY
およびFREETEMPORARY
を使用できます。
このプロシージャでは、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);
パラメータ
表2-29 OPENプロシージャ・パラメータ
パラメータ | 説明 |
---|---|
|
LOBのロケータ |
|
オープンする |
使用上の注意
読取り専用としてオープンされたLOBに書込みを試行すると、エラーが返されます。
OPEN
はサーバーへラウンドトリップをする必要があり、そのためにOPEN
コールに依存するコードが実行されます。
LOB操作はOPEN
およびCLOSE
コールで囲む必要はありません。ただし、LOBをオープンしている場合は、トランザクションをコミットまたはロールバックする前にクローズする必要があります。
トランザクションによってオープンされたすべてのLOBをクローズする前にトランザクションをコミットすると、エラーが発生します。エラーが戻された場合、LOBのオープンのステータスは廃棄されますが、トランザクションのコミットは正常に行われます。したがって、LOBおよび非LOBデータの両方に対するすべての変更トランザクションはコミットされます。
このプロシージャは、指定したLOBの先頭からの絶対オフセットから開始するLOBの一部を読み取り、buffer
パラメータに、(BLOBの場合は)指定されたバイト数を戻し、(CLOBまたはNCLOBの場合は)文字数を戻します。
構文
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);
パラメータ
表2-30 READプロシージャ・パラメータ
パラメータ | 説明 |
---|---|
|
LOBのロケータ |
|
( ( |
|
LOBの先頭からのオフセット(起点: 1)(BLOBの場合はバイト数、CLOBまたはNCLOBの場合は文字数で指定します) |
|
読取り操作からの出力バッファ |
使用上の注意
入力offset
がLOBの終了を超えた位置をポイントしている場合、amount
は0(ゼロ)に設定され、NO_DATA_FOUND
例外が発生します。
CLOBまたはNCLOBの場合、buffer
パラメータのVARCHAR2
バッファの形式はLOBのタイプに適したものである必要があります。指定したLOBがNCLOB
のタイプである場合、バッファにはNCHAR
データが含まれる必要があります。指定したLOBがCLOB
のタイプである場合、バッファにはCHAR
データが含まれる必要があります。
クライアントからREAD
をコールする場合、戻されたバッファにはクライアントのキャラクタ・セットのデータが含まれます。データベースは、バッファをユーザーに戻す前に、サーバーのキャラクタ・セットからクライアントのキャラクタ・セットにLOB値を変換します。
READ
は、読取り前に必要に応じてLOBを取得します。
例外
最大LOBサイズはBLOBの場合はBLOBMAXSIZE
で、CLOBの場合はCLOBMAXSIZE
です。
表2-31 READプロシージャの例外
例外 | 説明 |
---|---|
|
|
|
次のいずれかが該当します。
|
|
LOBの終了に達し、LOBにはこれ以上読み取るバイトまたは文字がありません。 |
このファンクションでは、指定したLOBの先頭からの指定したオフセットから開始する指定されたバイト数(BLOBの場合)または文字数(CLOBまたはNCLOBの場合)を戻します。
構文
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;
パラメータ
表2-32 SUBSTRファンクション・パラメータ
パラメータ | 説明 |
---|---|
|
LOBのロケータ |
|
読み込むバイト数(BLOBの場合)または文字数(CLOBまたはNCLOBの場合) |
|
LOBの先頭からのオフセット(起点: 1)(BLOBの場合はバイト数、CLOBまたはNCLOBの場合は文字数で指定します) |
戻り値
次のいずれかを戻します。
BLOBの場合は、RAW
バイト数
CLOBまたはNCLOBの場合は、VARCHAR2
文字数
いずれかの入力パラメータがNULL
か、次のいずれかが該当する場合はNULL
amount
< 1またはamount
> 32767バイト(または同等の文字)
offset
< 1またはoffset
>最大LOBサイズ
ここで、最大LOBサイズはBLOBの場合はBLOBMAXSIZE
で、CLOBの場合はCLOBMAXSIZE
です。
使用上の注意
固定幅のn
バイトのCLOBまたはNCLOBの場合は、SUBSTR
に対する入力amountの指定が(32767/n
)を超えると、SUBSTR
では、(32767/n
)の長さの文字バッファまたはCLOBの長さのうち、小さい方を戻します。可変幅キャラクタ・セットのCLOBの場合、n
はCLOBの文字に使用される最大バイト幅です。
CLOBまたはNCLOBの場合、VARCHAR2
戻りバッファの形式はLOBの形式に適したものである必要があります。指定したLOBがNCLOB
のタイプである場合、バッファにはNCHAR
データが含まれる必要があります。指定したLOBがCLOB
のタイプである場合、バッファにはCHAR
データが含まれる必要があります。
クライアントからSUBSTR
をコールする場合、戻されたバッファにはクライアントのキャラクタ・セットのデータが含まれます。データベースは、バッファをユーザーに戻す前に、サーバーのキャラクタ・セットからクライアントのキャラクタ・セットにLOB値を変換します。
SUBSTR
は、LOBに格納されている文字に基づいて8191個以上の文字を戻します。使用可能なバッファを超える文字バイト数が原因ですべての文字が戻されない場合、新しいオフセットでSUBSTR
をコールして残りの文字を読み取るか、すべてのデータを抽出するまでサブプログラムのコールをループする必要があります。
SUBSTR
は、読取り前に必要に応じてLOBを取得します。
このプロシージャは、newlen
パラメータで指定した長さにLOBを切り捨てます。新しい必要なデータ長をBLOBの場合はバイト数で、CLOBまたはNCLOBの場合は文字数で指定します。
構文
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);
パラメータ
表2-33 TRIMプロシージャ・パラメータ
パラメータ | 説明 |
---|---|
|
LOBのロケータ |
|
目的の切捨て後のLOB値の長さ(BLOBの場合はバイト数、CLOBまたはNCLOBの場合は文字数で指定します) |
使用上の注意
空のLOBを削除しようとすると、アクションは実行されず、TRIM
によってエラーが戻されません。
newlen
で指定した新しい長さがLOBのサイズよりも大きい場合は、例外が発生します。
LOBへの書込み操作は、OPEN
およびCLOSE
コールで囲むことをお薦めします(必須ではありません)。ただし、操作を実行する前にLOBをオープンした場合は、トランザクションのコミットまたはロールバックを実行する前にクローズする必要があります。
TRIM
は、LOBの長さを変更する前に、指定する新しい長さが0(ゼロ)の場合を除き、必要に応じてLOBを取得します。
例外
最大LOBサイズはBLOBの場合はBLOBMAXSIZE
で、CLOBの場合はCLOBMAXSIZE
です。
表2-34 TRIMプロシージャの例外
例外 | 説明 |
---|---|
|
|
|
次のいずれかが該当します。
|
|
問合せ内でLOB書込みを実行できません(これはTimesTenでは実行できません。) |
|
LOBでLOBバッファを有効にした状態では操作を実行できません。 |
このプロシージャは、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);
パラメータ
表2-35 WRITEプロシージャ・パラメータ
パラメータ | 説明 |
---|---|
|
LOBのロケータ |
|
書き込むバイト数(BLOBの場合)または文字数(CLOBまたはNCLOBの場合) |
|
LOBの先頭からの書込み操作のオフセット(起点: 1)(BLOBの場合はバイト数、CLOBまたはNCLOBの場合は文字数で指定します) |
|
書込み用データの入力バッファ |
使用上の注意
指定したamountがバッファのデータより多い場合はエラーが発生します。入力amount
がバッファのデータより少ない場合は、バッファからその量のバイト数または文字数のみLOBに書き込まれます。指定したオフセットが、現在そのLOBに格納されているデータの終わりを超えている場合は、オフセットに到達するためにLOBに、0(ゼロ)バイトのFILLER(BLOBの場合)または空白(CLOBまたはNCLOBの場合)が挿入されます。
CLOBまたはNCLOBの場合、buffer
パラメータのVARCHAR2
バッファの形式はLOBのタイプに適したものである必要があります。指定したLOBがNCLOB
のタイプである場合、バッファにはNCHAR
データが含まれる必要があります。指定したLOBがCLOB
のタイプである場合、バッファにはCHAR
データが含まれる必要があります。
クライアントからWRITE
をコールする場合、バッファにはクライアントのキャラクタ・セットのデータが含まれる必要があります。データベースは、バッファ・データをLOBに書き込む前に、クライアント側のバッファをサーバー側のキャラクタ・セットに変換します。
LOBへの書込み操作は、OPEN
およびCLOSE
コールで囲むことをお薦めします(必須ではありません)。ただし、操作を実行する前にLOBをオープンした場合は、トランザクションのコミットまたはロールバックを実行する前にクローズする必要があります。
WRITE
は、LOBに書き込む前に、書込みがLOB全体を上書きするように指定されている場合を除き、必要に応じてそれを取得します。
例外
最大LOBサイズはBLOBの場合はBLOBMAXSIZE
で、CLOBの場合はCLOBMAXSIZE
です。
表2-36 WRITEプロシージャの例外
例外 | 説明 |
---|---|
|
|
|
次のいずれかが該当します。
|
|
問合せ内でLOB書込みを実行できません(これはTimesTenでは実行できません。) |
|
LOBでLOBバッファを有効にした状態では操作を実行できません。 |
このプロシージャは、指定された量のデータをLOBの後ろ追加します。データは、buffer
パラメータから書き込まれます。(APPEND
プロシージャとは混同しないでください。)
構文
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);
パラメータ
表2-37 WRITEAPPENDプロシージャ・パラメータ
パラメータ | 説明 |
---|---|
|
LOBのロケータ |
|
書き込むバイト数(BLOBの場合)または文字数(CLOBまたはNCLOBの場合) |
|
書込み用データの入力バッファ |
使用上の注意
入力amountがバッファのデータより多い場合はエラーが発生します。入力amountがバッファのデータより少ない場合は、バッファからそのamount
のバイト数または文字数のみLOBに追加します。
CLOBまたはNCLOBの場合、buffer
パラメータのVARCHAR2
バッファの形式はLOBのタイプに適したものである必要があります。指定したLOBがNCLOB
のタイプである場合、バッファにはNCHAR
データが含まれる必要があります。指定したLOBがCLOB
のタイプである場合、バッファにはCHAR
データが含まれる必要があります。
クライアントからWRITEAPPEND
をコールする場合、バッファにはクライアントのキャラクタ・セットのデータが含まれる必要があります。データベースは、バッファ・データをLOBに書き込む前に、クライアント側のバッファをサーバー側のキャラクタ・セットに変換します。
LOBへの書込み操作は、OPEN
およびCLOSE
コールで囲むことをお薦めします(必須ではありません)。ただし、操作を実行する前にLOBをオープンした場合は、トランザクションのコミットまたはロールバックを実行する前にクローズする必要があります。
WRITEAPPEND
は、LOBに追加する前に、必要に応じてそれを取得します。
例外