DBMS_LOBパッケージは、BLOB、CLOB、およびNCLOBを操作するためのサブプログラムを提供します。DBMS_LOBを使用すると、LOBの特定の部分またはLOB全体に対するアクセスおよび操作ができます。

この章の内容は次のとおりです。

DBMS_LOBの使用方法

概要

セキュリティ・モデル

定数

データ・タイプ

ルールおよび制限

使用上の注意

例外

DBMS_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を設定して定義者の権限または実行者の権限のどちらを使用するのかを指示できます。次に例を示します。

または

AUTHIDについては、『Oracle TimesTen In-Memory Database PL/SQL開発者ガイド』の定義者の権限および実行者の権限に関する説明を参照してください。一時LOBに関係するセキュリティ・モデルについては「使用上の注意」を参照してください。

DBMS_LOBパッケージでは、表2-1に示す定数が使用されます。

表2-1 DBMS_LOBの定数

CALL

BINARY_INTEGER

12

コール継続時間を含む一時LOBを作成します。

DEFAULT_CSID

INTEGER

0

これがデフォルトのキャラクタ・セットIDです。

DEFAULT_LANG_CTX

INTEGER

0

これがデフォルトの言語コンテキストです。

LOB_READONLY

BINARY_INTEGER

0

指定したLOBを読取り専用モードでオープンします。

LOB_READWRITE

BINARY_INTEGER

1

指定したLOBを読取り/書取りモードでオープンします。

BLOBMAXSIZE

INTEGER

16777216(16 MB)

BLOBの最大サイズをバイトで設定します。

CLOBMAXSIZE

INTEGER

4194304(4 MB)

CLOBの最大サイズをバイトで設定します。

NO_WARNING

INTEGER

0

成功し、警告メッセージがないことを示します。

SESSION

BINARY_INTEGER

10

セッション継続時間を含む一時LOBを作成します。

注意: TimesTenでは、トランザクションの終了時にLOBの継続時間は終了します。対応するロケータがトランザクションの終了時に無効になっている場合、一時LOBのコンテンツは破棄されます。

TRANSACTION

BINARY_INTEGER

11

トランザクション継続時間を含む一時LOBを作成します。

WARN_INCONVERTIBLE_CHAR

INTEGER

1

変換できない文字があることを示すために変換ファンクションで使用されます。

注意:

PLS_INTEGERデータ・タイプとBINARY_INTEGERデータ・タイプは同じです。このドキュメントでは、リファレンス情報でデータ・タイプ(表タイプ、レコード・タイプ、サブプログラム・パラメータ、サブプログラム戻り値など)を示す場合にBINARY_INTEGERを使用しますが、説明および例ではいずれも使用される場合があります。

INTEGERデータ・タイプとNUMBER(38)データ・タイプも同じです。このドキュメントでは、全体をとおしてINTEGERを使用します。

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

表2-2 DBMS_LOBが使用するデータ・タイプ

BLOB

ソースまたは宛先のバイナリLOB

RAW

ソースまたは宛先のRAWバッファ(BLOBで使用)

CLOB

ソースまたは宛先の文字LOB(NCLOBを含む)

VARCHAR2

ソースまたは宛先の文字バッファ(CLOBおよびNCLOBで使用)

INTEGER

バッファまたはLOBのサイズ、LOBへのオフセットまたはアクセス量(BLOBの場合はバイト数、CLOBまたはNCLOBの場合は文字数)

DBMS_LOBパッケージは特別なタイプを定義しません。

NCLOBは、固定幅および可変幅のマルチバイト各国語キャラクタ・セットを格納するためのCLOBです。

CLOB用のDBMS_LOBサブプログラムの仕様部にある句ANY_CSを使用すると、CLOBタイプでCLOBまたはNCLOBロケータ変数を入力として受け入れることができます。

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

最大LOBサイズ

最大バッファ・サイズ

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

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にはシングルバイト文字の場合は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)を示す入力ロケータを用意する必要があります。

重要:

TimesTenでは、LOBロケータはトランザクションが終了すると無効になります。

LOBロケータを使用するAPIを介したLOBの操作では、TimesTenの一時領域が使用されます。このような操作をかなりの回数実行すると、TimesTenの一時データ・パーティションのサイズを拡大しなければならなくなる場合があります。詳細は、『Oracle TimesTen In-Memory Databaseリファレンス』のTempSizeに関する説明を参照してください。

データベースで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サブプログラム)はサポートしていません。

この後の項では、次の項目について説明します。

永続LOB

一時LOB

表に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の例外

ACCESS_ERROR

22925

LOBに書き込もうとしているデータ量が多すぎます。TimesTenでは、BLOBのサイズは16 MBに、CLOBまたはNCLOBのサイズは4 MBに制限されています。

BUFFERING_ENABLED

22279

LOBバッファを有効にした状態では操作を実行できません。

CONTENTTYPE_TOOLONG

43859

contenttype文字列の長さが、定義されている最大長を超えています。contenttype文字列の長さを変更し、操作を再試行してください。

CONTENTTYPEBUF_WRONG

43862

contenttypeバッファの長さが、定義されている定数より短くなっています。contenttypeバッファの長さを変更し、操作を再試行してください。

INVALID_ARGVAL

21560

引数はNULL以外の有効な値である必要がありますが、転送された引数値はNULL、無効または範囲外です。

NO_DATA_FOUND

1403

これは、ループ読取り操作でLOBの終了を示すインジケータです。ハード・エラーではありません。

QUERY_WRITE

14553

問合せ内でLOB書込みを実行できません(これはTimesTenでは実行できません。)

VALUE_ERROR

6502

これは、サブプログラムのパラメータ値が無効なためのPL/SQLエラーです。

注意:

表2-4 DBMS_LOBのサブプログラム

APPENDプロシージャ

ソースLOBの内容を宛先LOBに追加します。

CLOSEプロシージャ

オープンされているLOBをクローズします。

COMPAREファンクション

2つのLOB全体、または2つのLOBの一部を比較します。

CONVERTTOBLOBプロシージャ

ソースCLOBまたはNCLOBから文字データを読み取り、文字データを指定したキャラクタ・セットに変換して、変換したデータをバイナリ形式で宛先BLOBに書き込み、新しいオフセットを戻します。

CONVERTTOCLOBプロシージャ

ソースBLOBを取得し、指定したキャラクタ・セットを使用して、ソースのバイナリ・データを文字データに変換し、文字データを宛先CLOBまたはNCLOBに書き込み、新しいオフセットを戻します。

COPYプロシージャ

ソースLOBの全体または一部を宛先LOBにコピーします。

CREATETEMPORARYプロシージャ

一時データ・パーティションに一時LOBを作成します。

ERASEプロシージャ

LOBの全体または一部を消去します。

FREETEMPORARYプロシージャ

一時データ・パーティションの一時LOBを解放します。

GETCHUNKSIZEファンクション

LOB値を格納するLOBチャンクの使用領域容量を戻します。

GETLENGTHファンクション

LOB値の長さを、BLOBの場合はバイト数で、CLOBの場合は文字数で戻します。

GET_STORAGE_LIMITファンクション

指定したLOBのLOBタイプの格納の上限を戻します。

INSTRファンクション

LOBにおけるパターンのn番目の出現位置を戻します。

ISOPENファンクション

LOBが入力ロケータを使用して、すでにオープンされたかどうかをチェックします。

ISTEMPORARYファンクション

ロケータが一時LOBをポイントしているかどうかをチェックします。

OPENプロシージャ

LOB(永続または一時)を、指定された読取り/書込みまたは読取り専用モードでオープンします。

READプロシージャ

指定されたオフセットからLOBのデータを読み取ります。

SUBSTRファンクション

指定されたオフセットからLOB値の一部を戻します。

TRIMプロシージャ

指定された長さまでLOB値を切り捨てます。

WRITEプロシージャ

指定されたオフセットからLOBにデータを書き込みます。

WRITEAPPENDプロシージャ

バッファをLOBの終了に追加します。

このプロシージャでは、ソースLOBの内容を宛先LOBに追加します。ソースLOBを完全に追加します(WRITEAPPENDプロシージャとは混同しないでください。)

注意:

構文

パラメータ

表2-5 APPENDプロシージャのパラメータ

dest_lob

データを追加するLOBのロケータ

src_lob

データを読み取るLOBのロケータ

使用上の注意

LOBへの書込み操作は、OPENおよびCLOSEコールで囲むことをお薦めします(必須ではありません)。ただし、操作を実行する前にLOBをオープンした場合は、トランザクションのコミットまたはロールバックを実行する前にクローズする必要があります。

例外

表2-6 APPENDプロシージャの例外

VALUE_ERROR

ソースまたは宛先LOBのいずれかがNULLです。

QUERY_WRITE

問合せ内でLOB書込みを実行できません(これはTimesTenでは実行できません。)

BUFFERING_ENABLED

いずれかのLOBでLOBバッファを有効にした状態では操作を実行できません。

例

ここでは、APPENDプロシージャの使用例を示します。

(SQLスクリプトからコマンドを実行した後、出力が表示されます。)

このプロシージャでは、すでにオープンされているLOBをクローズします。

構文

パラメータ

表2-7 CLOSEプロシージャ・パラメータ

lob_loc

LOBのロケータ

使用上の注意

CLOSEでは、サーバーへのラウンドトリップが必要になります。

LOB操作はOPENおよびCLOSEコールで囲む必要はありません。ただし、LOBをオープンしている場合は、トランザクションをコミットまたはロールバックする前にクローズする必要があります。

トランザクションによってオープンされたすべてのLOBをクローズする前にトランザクションをコミットすると、エラーが発生します。エラーが戻された場合、LOBのオープンのステータスは廃棄されますが、トランザクションのコミットは正常に行われます。したがって、LOBおよび非LOBデータに対するすべての変更トランザクションはコミットされます。

例外

エラーは、LOBがオープンしていない場合に戻されます。

このファンクションは、2つのLOB全体、または2つのLOBの一部を比較します。

構文

パラメータ

表2-8 COMPAREファンクション・パラメータ

lob_1

比較する1番目のLOBのロケータ

lob_2

比較する2番目のLOBのロケータ

amount

比較するバイト数(BLOBの場合)または文字数(CLOBまたはNCLOB)

offset_1

1番目のLOBのバイト数または文字数でのオフセット(起点: 1)

offset_2

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の任意の組合せで使用できます。

構文

パラメータ

表2-9 CONVERTTOBLOBプロシージャ・パラメータ

dest_lob

宛先LOBのロケータ

src_clob

ソースLOBのロケータ

amount

ソースLOBから変換する文字数

CLOBまたはNCLOB全体を変換する場合、定数CLOBMAXSIZEを渡します。他の値を渡す場合は、LOBのサイズ以下である必要があります。

dest_offset

(IN)宛先LOBの書込み開始位置を示すオフセット(バイト数で指定します)

LOBの先頭から開始するには1の値を指定します。

(OUT)書込み終了位置の次の位置を示す新しいオフセット(バイト数で指定します)

src_offset

(IN)ソースLOBの読込み開始位置を示すオフセット(文字数で指定します)

(OUT)ソースLOBの読込み終了位置の次の位置を示すオフセット(文字数で示します)

blob_csid

変換BLOBデータのキャラクタ・セットID

lang_context

(IN)現行の変換に関する、シフト・ステータスなどの言語コンテキスト(TimesTenでは無視されます)

(OUT)現在の変換が実行されたときの言語コンテキスト(TimesTenでは0に設定されます)

このパラメータは、TimesTenではサポートされていません。

warning

警告メッセージ

このパラメータは、TimesTenではサポートされていません。

使用上の注意

事前条件

CONVERTTOBLOBをコールする前に、次の事前条件を満たしている必要があります。

ソースと宛先の両方のLOBが存在している。

宛先LOBが永続LOBの場合、行がロックされている。行をロックするには、SELECT文のFOR UPDATE句を使用して、LOBを選択します。

定数およびデフォルト

すべてのパラメータが必要です。各OUTまたはIN OUTパラメータに変数を渡す必要があります。各INパラメータに変数または値を渡す必要があります。

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

表2-10 CONVERTTOBLOBの一般的な値

amount

CLOBMAXSIZE (IN)

LOB全体を変換します。

dest_offset

1(IN)

先頭から開始します。

src_offset

1(IN)

先頭から開始します。

blob_csid

DEFAULT_CSID (IN)

デフォルトのキャラクタ・セットID(ソースCLOBと同じIDを使用します)。

lang_context

DEFAULT_LANG_CTX (IN)

これがデフォルトの言語コンテキストです(TimesTenでは無視されます)。

warning

NO_WARNING (OUT)

WARN_INCONVERTIBLE_CHAR (OUT)

これは警告メッセージです(TimesTenでは無視されます)。

一般的な注意

blob_csidパラメータに宛先BLOBの目的のキャラクタ・セットIDを指定する必要があります。0値を渡す場合、データベースでは目的のキャラクタ・セットがソースCLOBのキャラクタ・セットと同じであると想定されます。

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

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

例外

表2-11 CONVERTTOBLOBプロシージャの例外

VALUE_ERROR

入力パラメータのいずれかがNULLまたは無効です。

INVALID_ARGVAL

次のいずれかが該当します。

src_offset < 1またはsrc_offset > CLOBMAXSIZE

dest_offset < 1またはdest_offset > BLOBMAXSIZE

amount < 1またはamount > CLOBMAXSIZE

このプロシージャはソースBLOBを取得し、指定したキャラクタ・セットを使用して、ソースのバイナリ・データを文字データに変換し、文字データを宛先CLOBまたはNCLOBに書き込み、新しいオフセットを戻します。このプロシージャは、永続LOBまたは一時LOBの任意の組合せで使用できます。

構文

パラメータ

表2-12 CONVERTTOCLOBプロシージャ・パラメータ

dest_lob

宛先LOBのロケータ

src_blob

ソースLOBのロケータ

amount

ソースLOBから変換するバイト数

BLOB全体を変換する場合、定数BLOBMAXSIZEを渡します。他の値を渡す場合は、BLOBのサイズ以下である必要があります。

dest_offset

(IN)宛先LOBの書込み開始位置を示すオフセット(文字数で指定します)

LOBの先頭から開始するには1の値を指定します。

(OUT)書込み終了位置の次の位置を示す新しいオフセット(文字で指定します)

このオフセットは、常に書込み終了位置の後にある最初の完全な文字をポイントします。

src_offset

(IN)ソースLOBの読込み開始位置を示すオフセット(バイト数で指定します)

(OUT)ソースLOBの読込み終了位置の次の位置を示すオフセット(バイト数で示します)

blob_csid

ソースBLOBデータのキャラクタ・セットID

lang_context

(IN)現行の変換に関する、シフト・ステータスなどの言語コンテキスト(TimesTenでは無視されます)

(OUT)現在の変換が実行されたときの言語コンテキスト(TimesTenでは0に設定されます)

このパラメータは、TimesTenではサポートされていません。

warning

警告メッセージ

このパラメータは、TimesTenではサポートされていません。

使用上の注意

事前条件

CONVERTTOCLOBをコールする前に、次の事前条件を満たしている必要があります。

ソースと宛先の両方のLOBが存在している。

宛先LOBが永続LOBの場合、CONVERTTOCLOBプロシージャをコールする前に行がロックされている。行をロックするには、SELECT文のFOR UPDATE句を使用して、LOBを選択します。

定数およびデフォルト

すべてのパラメータが必要です。各OUTまたはIN OUTパラメータに変数を渡す必要があります。各INパラメータに変数または値を渡す必要があります。

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

表2-13 CONVERTTOCLOBの一般的な値

amount

BLOBMAXSIZE (IN)

LOB全体を変換します。

dest_offset

1(IN)

先頭から開始します。

src_offset

1(IN)

先頭から開始します。

blob_csid

DEFAULT_CSID (IN)

デフォルトのキャラクタ・セットID(宛先CLOBと同じIDを使用します)。

lang_context

DEFAULT_LANG_CTX (IN)

これがデフォルトの言語コンテキストです(TimesTenでは無視されます)。

warning

NO_WARNING (OUT)

WARN_INCONVERTIBLE_CHAR (OUT)

これは警告メッセージです(TimesTenでは無視されます)。

一般的な注意

blob_csidパラメータにソースBLOBの目的のキャラクタ・セットIDを指定する必要があります。0値を渡す場合、データベースでは目的のキャラクタ・セットが宛先CLOBのキャラクタ・セットと同じであると想定されます。

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

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

例外

表2-14 CONVERTTOCLOBプロシージャの例外

VALUE_ERROR

入力パラメータのいずれかがNULLまたは無効です。

INVALID_ARGVAL

次のいずれかが該当します。

src_offset < 1またはsrc_offset > BLOBMAXSIZE

dest_offset < 1またはdest_offset > CLOBMAXSIZE

amount < 1またはamount > BLOBMAXSIZE

このプロシージャでは、ソースLOBの全体または一部を宛先LOBにコピーします。ソースおよび宛先の両方のLOBに対するオフセット、およびコピーするバイト数または文字数を指定できます。

構文

パラメータ

表2-15 COPYプロシージャ・パラメータ

dest_lob

コピーする宛先LOBのロケータ

src_lob

コピー元のソースLOBのロケータ

amount

コピーするバイト数(BLOBの場合)または文字数(CLOBまたはNCLOBの場合)

dest_offset

宛先LOBのコピー開始位置を示すオフセット(起点: 1)(バイト数または文字数で指定します)

src_offset

ソース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プロシージャの例外

VALUE_ERROR

入力パラメータのいずれかがNULLまたは無効です。

INVALID_ARGVAL

次のいずれかが該当します。

src_offset < 1またはsrc_offset >最大LOBサイズ

dest_offset < 1またはdest_offset >最大LOBサイズ

amount < 1またはamount >最大LOBサイズ

QUERY_WRITE

問合せ内でLOB書込みを実行できません(これはTimesTenでは実行できません。)

BUFFERING_ENABLED

いずれかの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にコピーします。

INSERTおよびUPDATE文を使用したCLOBのコピー

Oracle DatabaseからのパススルーLOBは、TimesTenの表に対して実行するINSERTまたはUPDATE文とバインドできます。この方法で、パススルーLOBをTimesTen LOBにコピーできます。同様に、TimesTen LOBは、Oracle Databaseの表に対して実行するINSERTまたはUPDATE文とバインドできます。この方法で、TimesTen LOBをパススルーLOBにコピーできます。

この例では、これらの両方のシナリオを示しています。

このプロシージャは、一時データ・パーティションに一時BLOB、CLOBまたはNCLOBを作成します。

一時LOBの使用が終了したら、FREETEMPORARYプロシージャを使用します。

重要:

構文

パラメータ

表2-17 CREATETEMPORARYプロシージャ・パラメータ

lob_loc

一時LOBのロケータ

CLOBロケータのかわりにNCLOBロケータを指定することが許可されています。適切なキャラクタ・セットが使用されます。

cache

LOBをバッファ・キャッシュに読み込むかどうかを示すフラグ

dur

一時LOBをいつクリーン・アップするかのヒントを指定する、SESSIONまたはCALLの2つの事前定義された期間値の1つ

注意: いずれの設定も許可されますが、TimesTenではトランザクションが終了するとLOBロケータの継続時間が終了します。

使用上の注意

CREATETEMPORARYを使用して一時パススルーLOBを作成できません。

このプロシージャでは、LOBの全体または一部を消去します。

注意:

構文

パラメータ

表2-18 ERASEプロシージャ・パラメータ

lob_loc

LOBのロケータ

amount

(IN)消去するバイト数(BLOBの場合)または文字数(CLOBまたはNCLOBの場合)

(OUT)実際に消去されたバイト数

offset

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プロシージャの例外

VALUE_ERROR

入力パラメータのいずれかがNULLです。

INVALID_ARGVAL

次のいずれかが該当します。

amount < 1またはamount >最大LOBサイズ

offset < 1またはoffset >最大LOBサイズ

QUERY_WRITE

問合せ内でLOB書込みを実行できません(これはTimesTenでは実行できません。)

BUFFERING_ENABLED

LOBでLOBバッファを有効にした状態では操作を実行できません。

このプロシージャは、一時データ・パーティションの一時BLOB、CLOBまたはNCLOBを解放します。

CREATETEMPORARYプロシージャに関する説明も参照してください。

構文

パラメータ

表2-20 FREETEMPORARYプロシージャ・パラメータ

lob_loc

LOBのロケータ

使用上の注意

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

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

一時パススルーLOBはCREATETEMPORARYを使用しては作成できませんが、SQLなどその他のメカニズムで作成された場合、そのLOBでISTEMPORARYおよびFREETEMPORARYを使用できます。

TimesTenではこの機能をサポートしておらず、単純に値32Kを相互運用性のために戻します。この値は、TimesTenアプリケーションのパフォーマンスのチューニングには関係しません。(Oracle Databaseの機能については、『Oracle Database PL/SQLパッケージおよびタイプ・リファレンス』のGETCHUNKSIZEファンクションに関する説明を参照してください。)

構文

パラメータ

表2-21 GETCHUNKSIZEファンクション・パラメータ

lob_loc

LOBのロケータ

戻り値

値32Kは戻されますが、この数値に依存してアプリケーションのパフォーマンスのチューニングはしないようにする必要があります。

例外

表2-22 GETCHUNKSIZEプロシージャの例外

BUFFERING_ENABLED

LOBでLOBバッファを有効にした状態では操作を実行できません。

このファンクションでは指定したLOBの長さをバイト数(BLOBの場合)または文字数(CLOBまたはNCLOBの場合)で戻します。

構文

パラメータ

表2-23 GETLENGTHファンクションのパラメータ

lob_loc

LOBのロケータ

戻り値

LOB値の長さを、バイト数または文字数のINTEGER値で戻します。入力LOBまたはlob_locがNULLの場合、NULLが戻されます。

使用上の注意

以前に行ったERASEまたはWRITE操作でLOBに挿入された0(ゼロ)バイトまたは空白のFILLERは長さに含まれます。空のLOBの長さは0(ゼロ)です。

例外

表2-24 GETLENGTHプロシージャの例外

BUFFERING_ENABLED

LOBでLOBバッファを有効にした状態では操作を実行できません。

例

次の例は、GETLENGTHファンクションの使用方法を示します。

(SQLスクリプトからコマンドを実行した後、出力が表示されます。)

このファンクションは、指定したLOBのタイプの記憶域制限をバイト数で戻します。

構文

パラメータ

表2-25 GET_STORAGE_LIMITファンクション・パラメータ

lob_loc

LOBのロケータ

戻り値

TimesTenでは、指定したLOBのタイプのバイト単位での最大の記憶域容量値が単純に戻されます。つまり、BLOBの場合は16777216(16 MB)でCLOBまたはNCLOBの場合は4194304(4 MB)です。

このファンクションは、指定したオフセットを開始位置として、指定したLOBにおける指定したパターンのn番目に一致した位置を戻します。

注意:

構文

パラメータ

表2-26 INSTRファンクション・パラメータ

lob_loc

LOBのロケータ

pattern

テストするパターン

このパターンは、BLOBの場合はRAWバイトで、CLOBまたはNCLOBの場合は文字列(VARCHAR2)です。このパターンの最大サイズは16383バイトです。

offset

パターン・マッチングの開始位置を示す絶対オフセット(起点: 1)(BLOBの場合はバイト数、CLOBまたはNCLOBの場合は文字数で指定します)

nth

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が入力ロケータを使用してすでにオープンされているかどうかをチェックします。

構文

パラメータ

表2-27 ISOPENファンクション・パラメータ

lob_loc

LOBのロケータ

戻り値

戻り値は、LOBがオープンしている場合は1、していない場合は0(ゼロ)です。

使用上の注意

オープンのステータスは、ロケータではなくLOBに関連付けられています。LOBのオープンにロケータが使用されている場合、LOBのその他のロケータもそれをオープンとみなします。

ISOPENでは、LOBがオープンであるかの状態をサーバー上で調べる必要があるため、ラウンドトリップする必要があります。

このファンクションはLOBが一時的であるかどうかを判断します。

構文

パラメータ

表2-28 ISTEMPORARYプロシージャ・パラメータ

lob_loc

LOBのロケータ

戻り値

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

使用上の注意

FREETEMPORARYで一時LOBを解放すると、LOBロケータはNULLに設定されません。その結果、ISTEMPORARYでは、解放されたが明示的にNULLにリセットされていないロケータについては0 (ゼロ)を戻します。

一時パススルーLOBはCREATETEMPORARYを使用しては作成できませんが、SQLなどその他のメカニズムで作成された場合、そのLOBでISTEMPORARYおよびFREETEMPORARYを使用できます。

このプロシージャでは、LOBを指定された読取り専用または読取り/書込みモードでオープンします。

構文

パラメータ

表2-29 OPENプロシージャ・パラメータ

lob_loc

LOBのロケータ

open_mode

オープンするLOB_READONLYまたはLOB_READWRITEのいずれかのモード

使用上の注意

読取り専用としてオープンされたLOBに書込みを試行すると、エラーが返されます。

OPENはサーバーへラウンドトリップをする必要があり、そのためにOPENコールに依存するコードが実行されます。

LOB操作はOPENおよびCLOSEコールで囲む必要はありません。ただし、LOBをオープンしている場合は、トランザクションをコミットまたはロールバックする前にクローズする必要があります。

トランザクションによってオープンされたすべてのLOBをクローズする前にトランザクションをコミットすると、エラーが発生します。エラーが戻された場合、LOBのオープンのステータスは廃棄されますが、トランザクションのコミットは正常に行われます。したがって、LOBおよび非LOBデータの両方に対するすべての変更トランザクションはコミットされます。

このプロシージャは、指定したLOBの先頭からの絶対オフセットから開始するLOBの一部を読み取り、bufferパラメータに、(BLOBの場合は)指定されたバイト数を戻し、(CLOBまたはNCLOBの場合は)文字数を戻します。

構文

パラメータ

表2-30 READプロシージャ・パラメータ

lob_loc

LOBのロケータ

amount

(IN)読み込むバイト数(BLOBの場合)または文字数(CLOBまたはNCLOBの場合)

(OUT)実際に読み込まれたバイト数または文字数

offset

LOBの先頭からのオフセット(起点: 1)(BLOBの場合はバイト数、CLOBまたはNCLOBの場合は文字数で指定します)

buffer

読取り操作からの出力バッファ

使用上の注意

入力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プロシージャの例外

VALUE_ERROR

lob_loc、amountまたはoffsetのいずれかがNULLです。

INVALID_ARGVAL

次のいずれかが該当します。

amount < 1またはamount > 32767バイト(または同等の文字)またはbuffer容量

offset < 1またはoffset >最大LOBサイズ

NO_DATA_FOUND

LOBの終了に達し、LOBにはこれ以上読み取るバイトまたは文字がありません。amountパラメータの値が0(ゼロ)です。

このファンクションでは、指定したLOBの先頭からの指定したオフセットから開始する指定されたバイト数(BLOBの場合)または文字数(CLOBまたはNCLOBの場合)を戻します。

注意:

構文

パラメータ

表2-32 SUBSTRファンクション・パラメータ

lob_loc

LOBのロケータ

amount

読み込むバイト数(BLOBの場合)または文字数(CLOBまたはNCLOBの場合)

offset

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の場合は文字数で指定します。

注意:

構文

パラメータ

表2-33 TRIMプロシージャ・パラメータ

lob_loc

LOBのロケータ

newlen

目的の切捨て後のLOB値の長さ(BLOBの場合はバイト数、CLOBまたはNCLOBの場合は文字数で指定します)

使用上の注意

空のLOBを削除しようとすると、アクションは実行されず、TRIMによってエラーが戻されません。

newlenで指定した新しい長さがLOBのサイズよりも大きい場合は、例外が発生します。

LOBへの書込み操作は、OPENおよびCLOSEコールで囲むことをお薦めします(必須ではありません)。ただし、操作を実行する前にLOBをオープンした場合は、トランザクションのコミットまたはロールバックを実行する前にクローズする必要があります。

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

例外

最大LOBサイズはBLOBの場合はBLOBMAXSIZEで、CLOBの場合はCLOBMAXSIZEです。

表2-34 TRIMプロシージャの例外

VALUE_ERROR

lob_loc値がNULLです。

INVALID_ARGVAL

次のいずれかが該当します。

newlen < 0またはnewlen >最大LOBサイズ

QUERY_WRITE

問合せ内でLOB書込みを実行できません(これはTimesTenでは実行できません。)

BUFFERING_ENABLED

LOBでLOBバッファを有効にした状態では操作を実行できません。

このプロシージャは、LOBの先頭からの指定した絶対オフセットから開始し、指定された量のデータをLOBに書き込みます。データは、bufferパラメータから書き込まれます。

WRITEは、オフセット位置以降LOBにすでに存在しているデータを、指定した長さだけ置換(上書き)します。

注意:

構文

パラメータ

表2-35 WRITEプロシージャ・パラメータ

lob_loc

LOBのロケータ

amount

書き込むバイト数(BLOBの場合)または文字数(CLOBまたはNCLOBの場合)

offset

LOBの先頭からの書込み操作のオフセット(起点: 1)(BLOBの場合はバイト数、CLOBまたはNCLOBの場合は文字数で指定します)

buffer

書込み用データの入力バッファ

使用上の注意

指定した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プロシージャの例外

VALUE_ERROR

lob_loc、amountまたはoffsetがNULLであるか、範囲外であるか、無効です。

INVALID_ARGVAL

次のいずれかが該当します。

amount < 1またはamount > 32767バイト(または同等の文字)またはbufferの容量

offset < 1またはoffset >最大LOBサイズ

QUERY_WRITE

問合せ内でLOB書込みを実行できません(これはTimesTenでは実行できません。)

BUFFERING_ENABLED

LOBでLOBバッファを有効にした状態では操作を実行できません。

このプロシージャは、指定された量のデータをLOBの後ろ追加します。データは、bufferパラメータから書き込まれます。(APPENDプロシージャとは混同しないでください。)

注意:

構文

パラメータ

表2-37 WRITEAPPENDプロシージャ・パラメータ

lob_loc

LOBのロケータ

amount

書き込むバイト数(BLOBの場合)または文字数(CLOBまたはNCLOBの場合)

buffer

書込み用データの入力バッファ

使用上の注意

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

CLOBまたはNCLOBの場合、bufferパラメータのVARCHAR2バッファの形式はLOBのタイプに適したものである必要があります。指定したLOBがNCLOBのタイプである場合、バッファにはNCHARデータが含まれる必要があります。指定したLOBがCLOBのタイプである場合、バッファにはCHARデータが含まれる必要があります。

クライアントからWRITEAPPENDをコールする場合、バッファにはクライアントのキャラクタ・セットのデータが含まれる必要があります。データベースは、バッファ・データをLOBに書き込む前に、クライアント側のバッファをサーバー側のキャラクタ・セットに変換します。

LOBへの書込み操作は、OPENおよびCLOSEコールで囲むことをお薦めします(必須ではありません)。ただし、操作を実行する前にLOBをオープンした場合は、トランザクションのコミットまたはロールバックを実行する前にクローズする必要があります。

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

例外

表2-38 WRITEAPPENDプロシージャの例外

VALUE_ERROR

lob_loc、amountまたはoffsetがnullであるか、範囲外であるか、無効です。

INVALID_ARGVAL

次のいずれかが該当します。

amount < 1またはamount > 32767バイト(または同等の文字)またはbufferの容量

QUERY_WRITE

問合せ内でLOB書込みを実行できません(これはTimesTenでは実行できません。)

BUFFERING_ENABLED

LOBでLOBバッファを有効にした状態では操作を実行できません。