1. Database PL/SQLパッケージ・プロシージャおよびタイプ・リファレンス
  2. DBMS_LOB

93 DBMS_LOB

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

この章のトピックは、次のとおりです:

参照:

Oracle Database SecureFiles and Large Objects開発者ガイド

93.1 DBMS_LOBの概要

DBMS_LOBでは、BLOB、CLOBおよびNCLOBの読取りおよび変更ができ、BFILEに対しては、読取り専用操作を実行できます。LOB操作の大部分が、このパッケージによって提供されます。

93.2 DBMS_LOBの推奨されないサブプログラム

Oracle Database 12cリリース12.2では、DBMS_LOBパッケージでのDBMS_LOB.LOADFROMFILEプログラムの使用は推奨されていません。

ノート:

新しいアプリケーションでは、推奨されないプロシージャは使用しないことをお薦めします。推奨されない機能は、下位互換性を維持する目的のみでサポートされています。

かわりに、DBMS_LOB.LoadClobFromFileまたはDBMS_LOB.LoadBlobFromFileを使用してください。

93.3 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に関係するセキュリティ・モデルについては、「操作上のノート」を参照してください。

93.4 DBMS_LOBの定数

このトピックでは、DBMS_LOBパッケージで使用される定数について説明しています。

これらを、次の表に示します。

表93-1 DBMS_LOBの定数 - 基本

定数 タイプ 値 説明

CALL

PLS_INTEGER

12

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

FILE_READONLY

BINARY_INTEGER

0

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

LOB_READONLY

BINARY_INTEGER

0

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

LOB_READWRITE

BINARY_INTEGER

1

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

LOBMAXSIZE

INTEGER

18446744073709551615

LOBの最大サイズ(バイト単位)。

SESSION

PLS_INTEGER

10

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

表93-2 DBMS_LOBの定数: オプション・タイプ

定数 定義 値 説明

OPT_COMPRESS

BINARY_INTEGER

1

SECUREFILEの圧縮オプション値を設定/取得します。

OPT_DEDUPLICATE

BINARY_INTEGER

4

SECUREFILEの重複除外オプション値を設定/取得します。

OPT_ENCRYPT

BINARY_INTEGER

2

SECUREFILEの暗号化オプション値を取得します。

表93-3 DBMS_LOBの定数 - オプション値

定数 定義 値 説明

COMPRESS_OFF

BINARY_INTEGER

0

SETOPTIONSプロシージャに対しては、圧縮をオフに設定します。GETOPTIONSファンクションに対しては、圧縮はオフになっています。

COMPRESS_ON

BINARY_INTEGER

1

SETOPTIONSプロシージャに対しては、圧縮をオンに設定します。GETOPTIONSファンクションに対しては、圧縮はオンになっています。

DEDUPLICATE_OFF

BINARY_INTEGER

0

SETOPTIONSプロシージャに対しては、重複除外をオフに設定します。GETOPTIONSファンクションに対しては、重複除外はオフになっています。

DEDUPLICATE_ON

BINARY_INTEGER

4

SETOPTIONSプロシージャに対しては、重複除外をオンに設定します。GETOPTIONSファンクションに対しては、重複除外はオンになっています。

ENCRYPT_OFF

BINARY_INTEGER

0

GETOPTIONSファンクションに対しては、暗号化はオフになっています。

ENCRYPT_ON

BINARY_INTEGER

2

GETOPTIONSファンクションに対しては、暗号化はオンになっています。

表93-4 DBMS_LOBの定数 - DBFS状態値のタイプ

定数 定義 値 説明

DBFS_LINK_NEVER

PLS_INTEGER

0

LOBはアーカイブされていません。

DBFS_LINK_NO

PLS_INTEGER

2

LOBはアーカイブされていますが、RDBMSに読み込まれています。

DBFS_LINK_YES

PLS_INTEGER

1

LOBは現在アーカイブされています。

表93-5 DBMS_LOBの定数 - DBFSキャッシュ・フラグ

定数 定義 値 説明

DBFS_LINK_CACHE

PLS_INTEGER

1

LOBデータをアーカイブに書き込みますが、RDBMS内のデータはキャッシュされたバージョンとして保持します。

DBFS_LINK_NOCACHE

PLS_INTEGER

0

LOBデータをアーカイブに書き込み、RDBMSから削除します。

表93-6 DBMS_LOBの定数: その他

定数 定義 値 説明

CONTENTTYPE_MAX_SIZE

PLS_INTEGER

128

コンテンツ・タイプ文字列に使用できる最大バイト数

DBFS_LINK_PATH_MAX_SIZE

PLS_INTEGER

1024

DBFSパス名の最大長

93.5 DBMS_LOBデータ・タイプ

このトピックの表では、DBMS_LOBによって使用されるデータ・タイプを示します。

　

表93-7 DBMS_LOBで使用されるデータ・タイプ

タイプ 説明

BLOB

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

RAW

ソースまたは宛先のRAWバッファ(BLOBとともに使用されます)。

CLOB

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

VARCHAR2

ソースまたは宛先の文字バッファ(CLOBおよびNCLOBとともに使用されます)。

INTEGER

バッファまたはLOBのサイズ、LOBへのオフセットまたはアクセス量を指定します。

BFILE

データベースの外部に格納されているラージ・バイナリ・オブジェクト。

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

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

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

93.6 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つのデータベースに存在している必要があります。

参照:

『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』の「分散LOB」の章。

データベースで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に固有のノートは次のとおりです。

  1. DBMS_LOBのすべてのファンクションは、入力パラメータのいずれかがNULLの場合、NULLを戻します。LOBロケータがNULLとして入力されると、DBMS_LOBのすべてのプロシージャで例外が発生します。

  2. CLOBに基づく操作では、パラメータ(CLOBパラメータやVARCHAR2のバッファとパターンなど)の文字セットIDが一致しているかどうかは検証されません。この確認はユーザーが各自で行ってください。

  3. データ記憶域リソースは、DBAが異なるテンポラリ表領域を作成して制御します。必要に応じて、DBAはユーザーごとに別々のテンポラリ表領域を定義できます。

参照:

NOCOPY構文の詳細は、『Oracle Database PL/SQL言語リファレンス』を参照してください。

93.7 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例外が発生します。

    1. LOBデータの開始位置からの正の絶対オフセットのみ許可されています。LOBの終了位置からの負のオフセットは許可されていません。

    2. amount、offset、newlen、nthなど、サイズおよび位置を表すパラメータには、0(ゼロ)以外の正の値のみ許可されています。SQL文字列ファンクションおよび演算子で確認される負のオフセットおよび範囲は許可されていません。

    3. offset、amount、newlen、nthの値は、いずれのDBMS_LOBサブプログラムの場合でも、最大値はlobmaxsize 18446744073709551615(264)です。

    4. 固定幅のマルチバイト・キャラクタで構成される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文字はエラーになります。

93.8 DBMS_LOBの例外

このトピックの表では、DBMS_LOBの例外を示します。

表93-8 DBMS_LOBの例外

例外 コード 説明

ACCESS_ERROR

22925

LOBに書き込むデータが多すぎます。LOBサイズは最大4GBです。

BUFFERING_ENABLED

22279

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

CONTENTTYPE_TOOLONG

43859

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

CONTENTTYPEBUF_WRONG

43862

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

INVALID_ARGVAL

21560

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

INVALID_DIRECTORY

22287

現行の操作に使用しているディレクトリは、それが初めてアクセスされたか、または前回のアクセス以降にDBAによって変更された場合は無効です。

NO_DATA_FOUND

1403

ループ読取り操作用のENDOFLOBのインジケータ。ハード・エラーではありません。

NOEXIST_DIRECTORY

22285

ファイルに指定されているディレクトリが存在しません。

NOPRIV_DIRECTORY

22286

ユーザーに、そのディレクトリまたはファイルの操作に必要なアクセス権限がありません。

OPEN_TOOMANY

22290

オープン・ファイル数が最大値に達しました。

OPERATION_FAILED

22288

ファイル操作に失敗しました。

QUERY_WRITE

14553

問合せまたはPDMLパラレル実行サーバー内でLOB書込みが実行できません。

SECUREFILE_BADLOB

43856

SECUREFILEのみのコールで、SECUREFILE LOBタイプ以外のLOBが使用されました。

SECUREFILE_BADPARAM

43857

SECUREFILEサブプログラムに無効な引数が渡されました。

SECUREFILE_MARKERASED

43861

FRAGMENT_*操作に付けられたマークが削除されています。

SECUREFILE_OUTOFBOUNDS

43883

LOBの終わりを超えてFRAGMENT_*操作を実行しようとしました。

UNOPENED_FILE

22289

要求された操作の実行に使用するファイルがオープンされていません。

VALUE_ERROR

6502

サブプログラムのパラメータの値が無効のため、PL/SQLエラーが発生しました。

93.9 DBMS_LOBサブプログラムの要約

この表は、DBMS_LOBサブプログラムを示し、簡単に説明しています。

表93-9 DBMS_LOBパッケージのサブプログラム

サブプログラム 説明

APPENDプロシージャ

ソースLOBのコンテンツを宛先LOBに追加します。

CLOB2FILEプロシージャ

CLOBの内容をファイルに書き込みます。

CLOSEプロシージャ

オープンしている内部または外部LOBをクローズします。

COMPAREファンクション

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

CONVERTTOBLOBプロシージャ

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

CONVERTTOCLOBプロシージャ

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

COPYプロシージャ

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

COPY_DBFS_LINKプロシージャ

ソースLOBのDBFSリンクを宛先LOBにコピーします。

COPY_FROM_DBFS_LINK

LOBのデータをDBFSストアから取得します。

CREATETEMPORARYプロシージャ

一時BLOBまたはCLOBおよびそれに対応する索引をユーザーのデフォルト一時表領域に作成します。

DBFS_LINK_GENERATE_PATHファンクション

DBFSリンクの作成に使用する一意のファイル・パス名を戻します。

ERASEプロシージャ

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

FILECLOSEプロシージャ

ファイルをクローズします。

FILECLOSEALLプロシージャ

オープンしていたすべてのファイルをクローズします。

FILEEXISTSファンクション

ファイルがサーバー上に存在するかどうかを確認します。

FILEGETNAMEプロシージャ

ディレクトリ・オブジェクト名とファイル名を取得します。

FILEISOPENファンクション

入力BFILEロケータを使用してファイルがオープンされたかどうかをチェックします。

FILEOPENプロシージャ

ファイルをオープンします。

FRAGMENT_DELETEプロシージャ

LOBからの長さを指定した場合、指定したオフセット位置にあるデータを削除します。

FRAGMENT_INSERTプロシージャ

指定したデータ(最大32K)を、LOB内の指定したオフセット位置に挿入します。

FRAGMENT_MOVEプロシージャ

指定したオフセット位置から新しく指定したオフセット位置に、バイト単位(BLOB)または文字単位(CLOB/NCLOB)で移動します。

FRAGMENT_REPLACEプロシージャ

指定したオフセット位置にあるデータを指定したデータ(32k以下)で置き換えます。

FREETEMPORARYプロシージャ

デフォルト一時表領域にある一時BLOBまたはCLOBを解放します。

GET_DBFS_LINKファンクション

指定したSecureFileに関連付けられたDBFSリンク・パスを戻します。

GET_DBFS_LINK_STATEプロシージャ

指定したSecureFileの現在のDBFSリンク状態を取得します。

GETCHUNKSIZEファンクション

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

GETCONTENTTYPEファンクション

SETCONTENTTYPEプロシージャを使用して以前設定したコンテンツID文字列を戻します。

GETLENGTHファンクション

LOB値の長さを取得します。

GETOPTIONSファンクション

特定のLOBのoption_typeフィールドに対応する設定を取得します。

GET_STORAGE_LIMITファンクション

データベース構成のLOBの記憶域制限を戻します。

INSTRファンクション

LOBにあるパターンのn番目の一致のマッチング位置を戻します。

ISOPENファンクション

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

ISREMOTEファンクション

LOBがデータベースに対してローカルであるか、またはリモート・データベースに属しているかを確認します。

ISSECUREFILEファンクション

渡されるLOBロケータがSecurefiles LOB用の場合にTRUEを戻します。それ以外の場合は、FALSEを戻します。

ISTEMPORARYファンクション

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

LOADBLOBFROMFILEプロシージャ

BFILEデータを内部BLOBにロードします。

LOADCLOBFROMFILEプロシージャ

BFILEデータを内部CLOBにロードします。

LOADFROMFILEプロシージャ

BFILEデータを内部LOBにロードします。

Oracle Database 12cリリース12.2から、このプロシージャは非推奨になっています。

MOVE_TO_DBFS_LINKプロシージャ

指定したSecureFileデータをDBFSストアに書き込みます。

OPENプロシージャ

指定されたモードでLOB(内部、外部またはテンポラリ)をオープンします。

READプロシージャ

指定されたオフセット以降のLOBデータを読み込みます。

SET_DBFS_LINKプロシージャ

指定したSecureFileを指定したパス名にリンクします。データはパスにコピーされません。

SETCONTENTTYPEプロシージャ

LOB内のデータのコンテンツ・タイプ文字列値を設定します。

SETOPTIONSプロシージャ

LOB単位でCSCE機能を使用可能にして、デフォルトのLOB列設定より優先させます。

SUBSTRファンクション

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

TRIMプロシージャ

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

WRITEプロシージャ

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

WRITEAPPENDプロシージャ

LOBの終わり以降にバッファを書き込みます。

93.9.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);

パラメータ

表93-10 APPENDプロシージャのパラメータ

パラメータ 説明

dest_lob

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

src_lob

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

例外

表93-11 APPENDプロシージャの例外

例外 説明

VALUE_ERROR

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

QUERY_WRITE

問合せまたはPDMLパラレル実行サーバー内でLOB書込みが実行できません。

BUFFERING_ENABLED

いずれかのLOBでバッファが有効になっている場合、LOBバッファを有効にした状態では操作を実行できません。

使用上のノート

  • オープン/クローズ・インタフェース内のLOB操作のラップは必須ではありません。操作を実行する前にLOBをオープンしなかった場合、LOB列のファンクション索引およびドメイン索引は、コール中に更新されます。ただし、操作を実行する前にLOBをオープンした場合は、トランザクションのコミットを実行する前にクローズする必要があります。内部LOBがクローズされるときに、LOB列のファンクション索引およびドメイン索引が更新されます。

    オープン/クローズAPI内のLOB操作をラップしなかった場合、ファンクション索引およびドメイン索引はLOBへ書き込むたびに更新されます。これにより、パフォーマンスに悪影響を及ぼす可能性があります。したがって、LOBへの書込み操作をOPENまたはCLOSE文の中に囲むことをお薦めします。

  • アーカイブされているLOBでAPPENDをコールした場合は、最初のバイトが書き込まれる前にLOBが暗黙的に取得されます。

  • DBFSリンクであるSecureFiles LOBでAPPENDがコールされると、例外が発生します。

参照:

このプロシージャの使用方法の詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください。

93.9.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');

パラメータ

表93-12 CLOB2FILEプロシージャのパラメータ

パラメータ 説明

src_cl

ファイルに書き込むソースCLOBロケータ

file_loc

ファイルが存在しているディレクトリ・オブジェクト名

file_name

ファイル名

csid

CLOBロケータの文字セットID

  • Oracleの有効なIDを指定します。そうでない場合、エラーが戻されます。

  • 値が0の場合、出力ファイルの内容はデータベースの文字セットで表されます。

open_mode
出力ファイルをオープンするモード。

  • wb - 書込みバイト・モード。ファイルを上書きします。

デフォルト値はwbです。

93.9.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);

パラメータ

表93-13 CLOSEプロシージャのパラメータ

パラメータ 説明

lob_loc

LOBロケータ。詳細は、「操作上のノート」を参照してください。

例外

BFILEは存在しているが、オープンしていない場合、エラーは戻りません。エラーは、LOBがオープンしていない場合に戻されます。

使用上のノート

CLOSEでは、内部または外部LOBのいずれの場合もサーバーへのラウンドトリップが必要です。内部LOBの場合、CLOSEはクローズ・コールに依存するその他のコードをトリガーし、外部LOB (BFILE)の場合、CLOSEはサーバー側のオペレーティング・システム・ファイルを実際にクローズします。

オープン/クローズ・インタフェース内のすべてのLOB操作のラップは必須ではありません。ただし、LOBをオープンしている場合は、トランザクションのコミットを実行する前にクローズする必要があり、クローズしない場合は、エラーが発生します。内部LOBがクローズされるときに、LOB列のファンクション索引およびドメイン索引が更新されます。

トランザクションによってオープンされたすべてのLOBをクローズする前にトランザクションをコミットすると、エラーが発生します。エラーが戻された場合、LOBのオープンは廃棄されますが、トランザクションのコミットは正常に行われます。したがって、そのトランザクションにおけるLOBおよび非LOBデータの変更はすべてコミットされますが、ドメイン索引およびファンクションベースの索引は更新されません。このような場合は、LOB列のファンクション索引およびドメイン索引を再構築する必要があります。

参照:

このプロシージャの使用方法の詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください。

93.9.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);

パラメータ

表93-14 COMPAREファンクションのパラメータ

パラメータ 説明

lob_1

最初の比較対象のLOBロケータ。

lob_2

2番目の比較対象のLOBロケータ。

amount

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

offset_1

1番目のLOBの比較開始位置を示すオフセット(起点: 1)。バイト数または文字数で指定します。

offset_2

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からストリーミングされ、可能でない場合は例外が発生します。

例外

表93-15 BFILE操作に関するCOMPAREファンクションの例外

例外 説明

UNOPENED_FILE

ファイルが入力ロケータを使用してオープンされていません。

NOEXIST_DIRECTORY

ディレクトリが存在しません。

NOPRIV_DIRECTORY

ディレクトリに対する権限がありません。

INVALID_DIRECTORY

ディレクトリがファイルのオープン後に無効となりました。

INVALID_OPERATION

ファイルが存在しないか、またはファイルのアクセス権限がありません。

BUFFERING_ENABLED

いずれかのLOBでバッファが有効になっている場合、LOBバッファを有効にした状態では操作を実行できません。

参照:

このプロシージャの使用方法の詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください。

93.9.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);

パラメータ

表93-16 CONVERTTOBLOBプロシージャのパラメータ

パラメータ 説明

dest_lob

宛先LOBインスタンスのLOBロケータ。

src_clob

ソースLOBインスタンスのLOBロケータ。

amount

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

LOB全体をコピーする場合は、定数DBMS_LOB.LOBMAXSIZEを渡します。他の値を渡す場合は、LOBのサイズ以下である必要があります。

dest_offset

(IN)宛先LOBの書込み開始位置を示すオフセット(バイト数で指定します)。LOBの先頭から開始するには1の値を指定します。

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

src_offset

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

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

blob_csid

変換データの目的とする文字セットID。

lang_context

(IN)現行の変換に関する、シフト・ステータスなどの言語コンテキスト。

(OUT)現在の変換が実行されたときの言語コンテキスト。

この情報は、ユーザーがこの情報を使用してソース・データを失ったり、誤って解釈したりすることなく継続して変換できるようにするために戻されます。最初の変換の場合、または特に必要ない場合は、デフォルト値の0(ゼロ)を使用してください。

warning

(OUT)警告メッセージ。このパラメータは、変換時に何らかの異常が発生したことを示します。警告メッセージを確認する必要があります。

現在、発生する可能性があるのは、変換不可能な文字に関する警告のみです。これは、ソースの文字が宛先の文字に正しく変換できない場合に発生します。変換不可能な文字のかわりに、デフォルトの置換文字('?'など)が使用されます。このエラー・メッセージの戻り値は、DBMS_LOBパッケージの定数warn_inconvertible_charとして定義します。

使用上のノート

事前条件

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

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

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

定数およびデフォルト

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

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

表93-17 DBMS_LOB.CONVERTTOBLOBの一般的な値

パラメータ 値 説明

amount

LOBMAXSIZE(IN)

ファイル全体を変換します。

dest_offset

1 (IN)

先頭から開始します。

src_offset

1 (IN)

先頭から開始します。

blob_csid

DEFAULT_CSID (IN)

デフォルトのCSID。ソースLOBと同じCSIDを使用します。

lang_context

DEFAULT_LANG_CTX (IN)

デフォルトの言語コンテキスト。

warning

NO_WARNING (OUT)

WARN_INCONVERTIBLE_CHAR (OUT)

警告メッセージはありません。成功しました。

ソースの文字を正しく変換できません。

一般的なノート

  • blob_csidパラメータに宛先LOBの目的の文字セットを指定する必要があります。blob_csidには0(ゼロ)の値を渡せます。これを行う場合、データベースでは目的の文字セットがソースLOB文字セットと同じであると想定されます。

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

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

例外

表93-18に、このプロシージャがスローする可能性のある例外を示します。1列目は例外の文字列を示し、2列目は例外の原因となる可能性のあるエラー条件を説明しています。

表93-18 CONVERTTOBLOBプロシージャの例外

例外 説明

VALUE_ERROR

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

INVALID_ARGVAL

次の1つ以上を指定します。

- src_offsetまたはdest_offset < 1

- src_offsetまたはdest_offset > LOBMAXSIZE。

- amount < 1。

- amount > LOBMAXSIZE。

参照:

アプリケーション開発でのLOBの使用方法の詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください。

93.9.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);

パラメータ

表93-19 CONVERTTOCLOBプロシージャのパラメータ

パラメータ 説明

dest_lob

宛先LOBインスタンスのLOBロケータ。

src_blob

ソースLOBインスタンスのLOBロケータ。

amount

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

BLOB全体をコピーする場合は、定数DBMS_LOB.LOBMAXSIZEを渡します。他の値を渡す場合は、BLOBのサイズ以下である必要があります。

dest_offset

(IN)宛先LOBの書込み開始位置を示すオフセット(文字数で指定します)。LOBの先頭から開始するには1の値を指定します。

(OUT)書込み終了位置の次の位置を示す新しいオフセット(文字数で指定します)。このオフセットは、常に書込み終了位置の後にある最初の完全な文字をポイントします。

src_offset

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

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

blob_csid

ソース・データの文字セットID。

lang_context

(IN)現行の変換に関する、シフト・ステータスなどの言語コンテキスト。

(OUT)現在の変換が実行されたときの言語コンテキスト。

この情報は、ユーザーがこの情報を使用してソース・データを失ったり、誤って解釈したりすることなく継続して変換できるようにするために戻されます。最初の変換の場合、または特に必要ない場合は、デフォルト値の0(ゼロ)を使用してください。

warning

警告メッセージです。このパラメータは、変換時に何らかの異常が発生したことを示します。警告メッセージを確認する必要があります。

現在、発生する可能性があるのは、変換不可能な文字に関する警告のみです。これは、ソースの文字が宛先の文字に正しく変換できない場合に発生します。変換不可能な文字のかわりに、デフォルトの置換文字('?'など)が使用されます。このエラー・メッセージの戻り値は、DBMS_LOBパッケージの定数warn_inconvertible_charとして定義します。

使用上のノート

事前条件

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

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

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

定数およびデフォルト

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

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

表93-20 DBMS_LOB.CONVERTTOCLOBの一般的な値

パラメータ 値 説明

amount

LOBMAXSIZE(IN)

ファイル全体を変換します。

dest_offset

1 (IN)

先頭から開始します。

src_offset

1 (IN)

先頭から開始します。

csid

DEFAULT_CSID (IN)

デフォルトのCSID。宛先のCSIDを使用します。

lang_context

DEFAULT_LANG_CTX (IN)

デフォルトの言語コンテキスト。

warning

NO_WARNING (OUT)

WARN_INCONVERTIBLE_CHAR (OUT)

警告メッセージはありません。成功しました。

ソースの文字を正しく変換できません。

一般的なノート

  • blob_csidパラメータにソースLOBの目的の文字セットを指定する必要があります。blob_csidには0(ゼロ)の値を渡せます。そうすると、データベースで、目的の文字セットが宛先LOB文字セットと同じであるとみなされます。

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

  • CONVERTTOCLOBは、データの変換および書込み前に、必要に応じてソースまたは宛先LOB(あるいはその両方)を取得します。

例外

表93-21 CONVERTTOCLOBプロシージャの例外

例外 説明

VALUE_ERROR

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

INVALID_ARGVAL

次の1つ以上を指定します。

- src_offsetまたはdest_offset < 1

- src_offsetまたはdest_offset > LOBMAXSIZE。

- amount < 1。

- amount > LOBMAXSIZE。

参照:

アプリケーション開発でのLOBの使用方法の詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください。

93.9.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);

パラメータ

表93-22 COPYプロシージャのパラメータ

パラメータ 説明

dest_lob

コピー先のLOBロケータ。

src_lob

コピー元のLOBロケータ。

amount

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

dest_offset

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

src_offset

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

例外

表93-23  COPYプロシージャの例外

例外 説明

VALUE_ERROR

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

INVALID_ARGVAL

次のいずれかです。

- src_offsetまたはdest_offset < 1

- src_offsetまたはdest_offset > LOBMAXSIZE

- amount < 1。

- amount > LOBMAXSIZE

QUERY_WRITE

問合せまたはPDMLパラレル実行サーバー内でLOB書込みが実行できません。

BUFFERING_ENABLED

いずれかのLOBでバッファが有効になっている場合、LOBバッファを有効にした状態では操作を実行できません。

使用上のノート

  • 宛先LOBに指定したオフセットが、現在そのLOBに格納されているデータの終わりを超えている場合は、宛先BLOBまたはCLOBに、0(ゼロ)バイトのFILLERまたは空白がそれぞれ挿入されます。オフセットが宛先LOBの現行の長さより小さい場合、既存のデータは上書きされます。

  • ソースLOBのデータ長を超える量を指定してもエラーにはなりません。したがって、ソースLOBのデータを、src_offsetからソースLOBの終了までコピーする大量のコピーを指定できます。

  • オープン/クローズ・インタフェース内のLOB操作のラップは必須ではありません。操作を実行する前にLOBをオープンしなかった場合、LOB列のファンクション索引およびドメイン索引は、コール中に更新されます。ただし、操作を実行する前にLOBをオープンした場合は、トランザクションのコミットを実行する前にクローズする必要があります。内部LOBがクローズされるときに、LOB列のファンクション索引およびドメイン索引が更新されます。

  • オープン/クローズAPI内のLOB操作をラップしなかった場合、ファンクション索引およびドメイン索引はLOBへ書き込むたびに更新されます。これにより、パフォーマンスに悪影響を及ぼす可能性があります。したがって、LOBへの書込み操作をOPENまたはCLOSE文の中に囲むことをお薦めします。

  • コピー前に、ソースおよび宛先LOBが現在アーカイブされている場合は、それらが取得されます。完全に上書きする場合、宛先LOBは取り出されません。

  • ソースLOBがDBFSリンクの場合、データは、可能な場合はDBFSからストリーミングされ、可能でない場合は例外が発生します。宛先LOBがDBFSリンクの場合は、例外が発生します。

参照:

このプロシージャの使用方法の詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください。

93.9.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);

パラメータ

表93-24 COPY_DBFS_LINKプロシージャのパラメータ

パラメータ 説明

lob_loc_dst

lob_loc_srcと同じ記憶域データを参照するように設定されるLOB。

lob_loc_src

参照のコピー元のLOB。

flags

COPY_DBFS_LINKのオプション:

  • DBFS_LINK_NOCACHEは、DBFSリンクのみをコピーするように指定します。

  • DBFS_LINK_CACHEは、DBFSリンクをコピーし、lob_loc_dstによって指定されているデータベースLOBにデータを読み込んで、データがキャッシュされるように指定します。

例外

表93-25 COPY_DBFS_LINKプロシージャの例外

例外 説明

SECUREFILE_BADLOB

lob_loc_srcまたはlob_loc_dstは、SECUREFILEではありません。

INVALID_ARGVAL

lob_loc_src LOBはアーカイブされていません。

ORA-01555

ソースLOBがすでに取得されているか、アーカイブされていないか、またはロケータの取得後にLOBが(変更されたかどうかに関係なく)移行されています。

93.9.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);

パラメータ

表93-26 COPY_FROM_DBFS_LINKプロシージャのパラメータ

パラメータ 説明

lob_loc

アーカイブから取得されるLOB

使用上のノート

COPY_FROM_DBFS_LINKによって基礎となるDBFSファイルは削除されません。

LOBが正常に取得されると、COPY_FROM_DBFS_LINKでは暗黙的に成功が返されます。

例外

表93-27 COPY_FROM_DBFS_LINKプロシージャの例外

例外 説明

SECUREFILE_BADLOB

lob_locはSECUREFILEではありません。

ORA-01555

LOBがすでに取得されており、取得後に変更されているかどうか、ロケータの取得後にLOBが(変更されたかどうかに関係なく)移行されているかどうか。

93.9.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);

パラメータ

表93-28 CREATETEMPORARYプロシージャのパラメータ

パラメータ 説明

lob_loc

LOBロケータ。詳細は、「操作上のノート」を参照してください。

cache

LOBをバッファ・キャッシュに読み込むかどうかを指定します。

dur

2つの事前定義の継続時間(SESSION、またはCALL)のうちの1つ。一時LOBのクリーンアップをセッション終了時、またはコール終了時に行うかどうかを指定します。

durが省略された場合は、セッション継続時間が使用されます。

参照:

93.9.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);

パラメータ

表93-29 DBFS_LINK_GENERATE_PATHファンクションのパラメータ

パラメータ 説明

lob_loc

DBFSから取得されるLOB。

storage_dir

ファイルの親ディレクトリとなるDBFSディレクトリ。

例外

表93-30 DBFS_LINK_GENERATE_PATHファンクションの例外

例外 説明

SECUREFILE_WRONGTYPE

lob_locはSECUREFILEではありません。

使用上のノート

アーカイブに使用できるグローバルに一意なファイル・パス名を戻します。これは、このファンクションの各種LOBまたはLOBの各バージョンを対象としたすべてのコールで、グローバルに一意であることが保証されています。同一のLOBおよびバージョンでは、常に同じ名前になります。

93.9.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);

パラメータ

表93-31 ERASEプロシージャのパラメータ

パラメータ 説明

lob_loc

消去するLOBのロケータ。詳細は、「操作上のノート」を参照してください。

amount

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

offset

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

使用上のノート

  • LOBの中央部のデータが消去されると、BLOBまたはCLOBには、0(ゼロ)バイトのFILLERまたは空白がそれぞれ書き込まれます。

  • 指定した数を消去する前にLOB値の終わりに達した場合、実際に消去されたバイト数または文字数は、amountパラメータで指定した数と異なる場合があります。実際に消去された文字数またはバイト数は、amountパラメータに戻されます。

  • ERASEは、アーカイブされているLOBを取得します。ただし、消去がLOB全体に適用される場合を除きます。

  • 削除するLOBがDBFSリンクの場合、例外が発生します。

ノート:

LOBの長さは、LOBのセクションを消去しても減りません。LOB値の長さを減らす方法は、「TRIMプロシージャ」を参照してください。

例外

表93-32 ERASEプロシージャの例外

例外 説明

VALUE_ERROR

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

INVALID_ARGVAL

次のいずれかです。

- amount < 1またはamount > LOBMAXSIZE

- offset < 1またはoffset > LOBMAXSIZE

QUERY_WRITE

問合せまたはPDMLパラレル実行サーバー内でLOB書込みが実行できません。

BUFFERING_ENABLED

LOBでバッファが有効になっている場合、LOBバッファを有効にした状態では操作を実行できません。

使用上のノート

オープン/クローズ・インタフェース内のLOB操作のラップは必須ではありません。操作を実行する前にLOBをオープンしなかった場合、LOB列のファンクション索引およびドメイン索引は、コール中に更新されます。ただし、操作を実行する前にLOBをオープンした場合は、トランザクションのコミットを実行する前にクローズする必要があります。内部LOBがクローズされるときに、LOB列のファンクション索引およびドメイン索引が更新されます。

オープン/クローズAPI内のLOB操作をラップしなかった場合、ファンクション索引およびドメイン索引はLOBへ書き込むたびに更新されます。これにより、パフォーマンスに悪影響を及ぼす可能性があります。したがって、LOBへの書込み操作をOPENまたはCLOSE文の中に囲むことをお薦めします。

参照:

93.9.13 FILECLOSEプロシージャ

このプロシージャは、入力ロケータによってすでにオープンされているBFILEをクローズします。

ノート:

データベースには、BFILEに対する読取り専用アクセスしかありません。つまり、データベースを介してBFILEに書き込むことはできません。

構文

DBMS_LOB.FILECLOSE (
    file_loc IN OUT NOCOPY BFILE);

パラメータ

表93-33 FILECLOSEプロシージャのパラメータ

パラメータ 説明

file_loc

クローズするBFILEのロケータ

例外

表93-34 FILECLOSEプロシージャの例外

例外 説明

VALUE_ERROR

file_locの入力値がNULLです。

UNOPENED_FILE

ファイルが入力ロケータを使用してオープンされていません。

NOEXIST_DIRECTORY

ディレクトリが存在しません。

NOPRIV_DIRECTORY

ディレクトリに対する権限がありません。

INVALID_DIRECTORY

ディレクトリがファイルのオープン後に無効となりました。

INVALID_OPERATION

ファイルが存在しないか、またはファイルのアクセス権限がありません。

参照:

93.9.14 FILECLOSEALLプロシージャ

このプロシージャは、セッションでオープンされたすべてのBFILEをクローズします。

構文

DBMS_LOB.FILECLOSEALL;

例外

表93-35 FILECLOSEALLプロシージャの例外

例外 説明

UNOPENED_FILE

セッションでオープンされたファイルはありません。

参照:

93.9.15 FILEEXISTSファンクション

このファンクションは、指定したBFILEロケータが、サーバーのファイル・システムに実際に存在しているファイルを指しているかどうかを検証します。

構文

DBMS_LOB.FILEEXISTS (
   file_loc     IN    BFILE)
  RETURN INTEGER;

プラグマ

pragma restrict_references(FILEEXISTS, WNDS, RNDS, WNPS, RNPS);

パラメータ

表93-36 FILEEXISTSファンクションのパラメータ

パラメータ 説明

file_loc

BFILEのロケータ。

戻り値

表93-37 FILEEXISTSファンクションの戻り値

戻り値 説明

0

物理ファイルが存在しません。

1

物理ファイルが存在します。

例外

表93-38 FILEEXISTSファンクションの例外

例外 説明

NOEXIST_DIRECTORY

ディレクトリが存在しません。

NOPRIV_DIRECTORY

ディレクトリに対する権限がありません。

INVALID_DIRECTORY

ディレクトリがファイルのオープン後に無効となりました。

参照:

93.9.16 FILEGETNAMEプロシージャ

このプロシージャは、指定したBFILEロケータのディレクトリ・オブジェクトとファイル名を判別します。

ロケータに割り当てられたディレクトリ・オブジェクト名とファイル名を示すのみで、物理ファイルまたはディレクトリが実際に存在しているかどうかは判別しません。

dir_aliasバッファの最大値は30で、パス名全体の最大値は2000です。

構文

DBMS_LOB.FILEGETNAME (
   file_loc   IN    BFILE, 
   dir_alias  OUT   VARCHAR2,
   filename   OUT   VARCHAR2);

パラメータ

表93-39 FILEGETNAMEプロシージャのパラメータ

パラメータ 説明

file_loc

BFILEのロケータ

dir_alias

ディレクトリ・オブジェクト名

filename

BFILE名

例外

表93-40 FILEGETNAMEプロシージャの例外

例外 説明

VALUE_ERROR

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

INVALID_ARGVAL

dir_aliasまたはファイル名がNULLです。

参照:

このプロシージャの使用方法の詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください。

93.9.17 FILEISOPENファンクション

このファンクションは、BFILEが特定のFILEロケータでオープンされたかどうかを検証します。

構文

DBMS_LOB.FILEISOPEN (
   file_loc   IN    BFILE)
  RETURN INTEGER;

プラグマ

PRAGMA RESTRICT_REFERENCES(fileisopen, WNDS, RNDS, WNPS, RNPS);

パラメータ

表93-41 FILEISOPENファンクションのパラメータ

パラメータ 説明

file_loc

BFILEのロケータ。

戻り値

INTEGER: 0 =ファイルはオープンされていません。1 =ファイルはオープンされています。

使用上のノート

入力FILEロケータがFILEOPENプロシージャに渡されていない場合、そのファイルはこのロケータによってオープンされていないとみなされます。ただし、別のロケータがこのファイルをオープンしている可能性はあります。つまり、オープンされているかどうかは特定のロケータと関連付けられています。

例外

表93-42 FILEISOPENファンクションの例外

例外 説明

NOEXIST_DIRECTORY

ディレクトリが存在しません。

NOPRIV_DIRECTORY

ディレクトリに対する権限がありません。

INVALID_DIRECTORY

ディレクトリがファイルのオープン後に無効となりました。

参照:

93.9.18 FILEOPENプロシージャ

このプロシージャは、BFILEを読取り専用アクセスでオープンします。データベースを介してBFILEに書き込むことはできません。

構文

DBMS_LOB.FILEOPEN (
   file_loc   IN OUT NOCOPY  BFILE, 
   open_mode  IN             BINARY_INTEGER := file_readonly);

パラメータ

表93-43 FILEOPENプロシージャのパラメータ

パラメータ 説明

file_loc

BFILEのロケータ。

open_mode

ファイル・アクセスは読取り専用です。

例外

表93-44 FILEOPENプロシージャの例外

例外 説明

VALUE_ERROR

file_locまたはopen_modeがNULLです。

INVALID_ARGVAL

open_modeがFILE_READONLYではありません。

OPEN_TOOMANY

セッション内のオープン・ファイル数がsession_max_open_filesを超えています。

NOEXIST_DIRECTORY

file_locに関連付けられたディレクトリが存在しません。

INVALID_DIRECTORY

ディレクトリがファイルのオープン後に無効となりました。

INVALID_OPERATION

ファイルが存在しないか、またはファイルのアクセス権限がありません。

参照:

93.9.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);

パラメータ

表93-45 FRAGMENT_DELETEプロシージャのパラメータ

パラメータ 説明

lob_loc

LOBロケータ。詳細は、「操作上のノート」を参照してください。

amount

LOBから削除するバイト数(BLOB)または文字数(CLOB/NCLOB)。

offset

削除を開始するLOB内のオフセット位置を示すバイト数(BLOB)または文字数(CLOB/NCLOB)。

例外

表93-46 FRAGMENT_DELETEプロシージャの例外

例外 説明

INVALID_ARGVAL

パラメータ値が無効でした。

QUERY_WRITE

問合せ時に操作を実行できません。

BUFFERING_ENABLED

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

SECUREFILE_BADLOB

SECUREFILE LOBのみのコールで、SECUREFILE以外のLOBが使用されました。

SECUREFILE_OUTOFBOUNDS

LOBの終わりを超えてFRAGMENT_*操作を実行しようとしました。

93.9.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);

パラメータ

表93-47 FRAGMENT_INSERTプロシージャのパラメータ

パラメータ 説明

lob_loc

LOBロケータ。詳細は、「操作上のノート」を参照してください。

amount

LOBに挿入するバイト数(BLOB)または文字数(CLOB/NCLOB)。

offset

挿入を開始するLOB内のオフセット位置を示すバイト数(BLOB)または文字数(CLOB/NCLOB)。

buffer

LOBに挿入するデータ。

例外

表93-48 FRAGMENT_INSERTプロシージャの例外

例外 説明

INVALID_ARGVAL

パラメータ値が無効でした。

QUERY_WRITE

問合せ時に操作を実行できません。

BUFFERING_ENABLED

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

SECUREFILE_BADLOB

SECUREFILE LOBのみのコールで、SECUREFILE以外のLOBが使用されました。

SECUREFILE_OUTOFBOUNDS

LOBの終わりを超えてFRAGMENT_*操作を実行しようとしました。

使用上のノート

FRAGMENT_INSERTは、LOBに対する操作を実行する前に、必要に応じてLOBを取得します。

93.9.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);

パラメータ

表93-49 FRAGMENT_MOVEプロシージャのパラメータ

パラメータ 説明

lob_loc

LOBロケータ。詳細は、「操作上のノート」を参照してください。

amount

LOB内の移動するバイト数(BLOB)または文字数(CLOB/NCLOB)。

src_offset

データの挿入を開始するLOB内のオフセット位置を示すバイト数(BLOB)または文字数(CLOB/NCLOB)。

dest_offset

データの削除を開始するLOB内のオフセット位置を示すバイト数(BLOB)または文字数(CLOB/NCLOB)。

例外

表93-50 FRAGMENT_MOVEプロシージャの例外

例外 説明

INVALID_ARGVAL

パラメータ値が無効でした。

QUERY_WRITE

問合せ時に操作を実行できません。

BUFFERING_ENABLED

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

SECUREFILE_BADLOB

SECUREFILE LOBのみのコールで、SECUREFILE以外のLOBが使用されました。

SECUREFILE_OUTOFBOUNDS

LOBの終わりを超えてFRAGMENT_*操作を実行しようとしました。

使用上のノート

  • すべてのオフセット位置は事前移動オフセット位置です。

  • LOBの終わりを2以上超えてオフセット位置を設定することはできません。

  • FRAGMENT_MOVEは、LOBに対する操作を実行する前に、必要に応じてLOBを取得します。

93.9.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);

パラメータ

表93-51 FRAGMENT_REPLACEファンクションのパラメータ

パラメータ 説明

lob_loc

LOBロケータ。詳細は、「操作上のノート」を参照してください。

old_amount

LOB内で置き換えるバイト数(BLOB)または文字数(CLOB/NCLOB)。

new_amount

LOBに書き込むバイト数(BLOB)または文字数(CLOB/NCLOB)。

offset

データの挿入を開始するLOB内のオフセット位置を示すバイト数(BLOB)または文字数(CLOB/NCLOB)。

buffer

LOBに挿入するデータ。

例外

表93-52 FRAGMENT_REPLACEプロシージャの例外

例外 説明

INVALID_ARGVAL

パラメータ値が無効でした。

QUERY_WRITE

問合せ時に操作を実行できません。

BUFFERING_ENABLED

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

SECUREFILE_BADLOB

SECUREFILE LOBのみのコールで、SECUREFILE以外のLOBが使用されました。

SECUREFILE_OUTOFBOUNDS

LOBの終わりを超えてFRAGMENT_*操作を実行しようとしました。

使用上のノート

  • このプロシージャを起動することは、オフセット位置の既存のバイト数/文字数を削除して、オフセット位置に新しいバイト数/文字数を挿入することと同様です。

  • FRAGMENT_REPLACEは、LOBに対する操作を実行する前に、必要に応じてLOBを取得します。

93.9.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);

パラメータ

表93-53 FREETEMPORARYプロシージャのパラメータ

パラメータ 説明

lob_loc

LOBロケータ。詳細は、「操作上のノート」を参照してください。

使用上のノート

  • 新しい一時LOBの作成時に、同じ継続時間(セッション、コール)で使用されている一時LOBが存在しない場合は、新しい一時LOBセグメントが作成されます。一時LOBを解放すると、その一時LOBによって消費されていた領域が一時セグメントに解放されます。同じ継続時間が指定されているその他の一時LOBが存在しない場合は、一時セグメントも解放されます。

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

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

参照:

このプロシージャの使用方法の詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください。

93.9.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);

パラメータ

表93-54 GET_DBFS_LINKファンクションのパラメータ

パラメータ 説明

lob_loc

DBFSから取得されるLOB。

storage_path

DBFSに格納されているLOBへのパス。

lob_length

DBFSへの書込み時点でのLOBの長さ。

戻り値

アーカイブID。

例外

表93-55 GET_DBFS_LINKファンクションの例外

例外 説明

SECUREFILE_BADLOB

lob_locはSECUREFILEではありません。

ORA-01555

LOBがすでに取得されており、取得後に変更されている。または、ロケータの取得後にLOBが(変更されたかどうかに関係なく)移行されている。

93.9.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);

パラメータ

表93-56 GET_DBFS_LINK_STATEプロシージャのパラメータ

パラメータ 説明

lob_loc

アーカイブから取得されるLOB

storage_path

DBFS HSMストアに格納されているLOBへのパス。

state

DBFS_LINK_NEVER、DBFS_LINK_NOまたはDBFS_LINK_YESのいずれか

cached

LOBがアーカイブされており、アーカイブ時にキャッシュされるように指定されている場合。

例外

表93-57 GET_DBFS_LINK_STATEプロシージャの例外

例外 説明

SECUREFILE_BADLOB

lob_locはSECUREFILEではありません。

使用上のノート

  • 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に設定されます。

93.9.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);

パラメータ

表93-58 GETCONTENTTYPEファンクションのパラメータ

パラメータ 説明

lob_loc

コンテンツ・タイプを取得するLOB。

戻り値

戻されたコンテンツ・タイプ。

SecureFiles LOBにcontenttypeが関連付けられていない場合、GETCONTENTTYPE()はNULLを戻します。

例外

表93-59 GETCONTENTTYPEファンクションの例外

例外 説明

SECUREFILE_BADLOB

lob_locはSECUREFILEではありません。

関連項目

93.9.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);

パラメータ

表93-60 GET_STORAGE_LIMITファンクションのパラメータ

パラメータ 説明

lob_loc

LOBロケータ。詳細は、「操作上のノート」を参照してください。

戻り値

このファンクションから戻される値は、指定したLOBロケータの最大許容サイズです。BLOBの場合、戻り値は、LOBが存在する表領域のブロック・サイズによって異なり、表領域のブロック・サイズの(232)-1(4294967295)倍として計算されます。CLOB/NCLOBの場合、戻り値は、表領域のブロック・サイズの(232)-1(4294967295)倍をCLOB/NCLOBの文字幅で割った値になります。

使用方法

参照:

LOB記憶域制限の詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください。

93.9.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);

パラメータ

表93-61 GETCHUNKSIZEファンクションのパラメータ

パラメータ 説明

lob_loc

LOBロケータ。詳細は、「操作上のノート」を参照してください。

戻り値

戻り値は、使用可能なチャンク・サイズ(バイト単位)です。

使用上のノート

  • 基本的なLOBファイルの場合、このチャンク・サイズの倍数を使用して読取り/書込み要求を入力すると、パフォーマンスが向上します。LOBチャンクはバージョン化され、すべての書込みがチャンクを基準に行われると、余分なバージョン分割が行われず、重複もしないため、書込みの場合にはさらに利点があります。同じチャンクに対してWRITEコールを複数回発行するかわりに、1つのチャンク内でWRITEコールを十分な数だけまとめることができます。

    これらのパフォーマンスを向上させる方法は、SecureFilesには適用されません。

  • チャンク・サイズはLOBタイプ(BLOB、CLOB、NCLOB、Unicodeまたはその他の文字セット)とは無関係です。

参照:

このプロシージャの使用方法の詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください。

例外

表93-62 GETCHUNKSIZEプロシージャの例外

例外 説明

BUFFERING_ENABLED

LOBでバッファが有効になっている場合、LOBバッファを有効にした状態では操作を実行できません。

93.9.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);

パラメータ

表93-63 GETLENGTHファンクションのパラメータ

パラメータ 説明

file_loc

長さが戻されるLOBのファイル・ロケータ

戻り値

LOBの長さが、INTEGERとしてバイト数または文字数で戻されます。入力LOBがNULLの場合または入力lob_locがNULLの場合は、NULLが戻されます。BFILEの場合は、次の場合にエラーが戻されます。

例外

表93-64 GETLENGHTHプロシージャの例外

例外 説明

BUFFERING_ENABLED

LOBでバッファが有効になっている場合、LOBバッファを有効にした状態では操作を実行できません。

93.9.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;

パラメータ

表93-65 GETOPTIONSファンクションのパラメータ

パラメータ 説明

lob_loc

検査するLOBのロケータ。詳細は、「操作上のノート」を参照してください。

option_type

表93-2を参照してください

戻り値

戻り値は、渡されたオプション・タイプ(表93-2を参照)に応じたCOMPRESS_ON、ENCRYPT_ONおよびDEDUPLICATE_ONの組合せです(表93-3を参照)。

例外

表93-66 GETOPTIONSプロシージャの例外

例外 説明

INVALID_ARGVAL

パラメータ値が無効でした。

QUERY_WRITE

問合せ時に操作を実行できません。

BUFFERING_ENABLED

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

SECUREFILE_BADLOB

SECUREFILE LOBのみのコールで、SECUREFILE以外のLOBが使用されました。

使用上のノート

圧縮または複製解除の機能が備えられていないSecureFile列に対して、これらの機能をオンまたはオフにすることはできません。GetOptionsファンクションとSETOPTIONSプロシージャは、個々のSecureFilesに対して動作します。特定のSecureFileの機能をオフにしたり、SetOptionsによってすでにオフにされている機能をオンにすることはできますが、表の作成時にSecureFileに指定されていないオプションをオンにすることはできません。

93.9.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);

パラメータ

表93-67 INSTRファンクションのパラメータ

パラメータ 説明

lob_loc

検査するLOBのロケータ。詳細は、「操作上のノート」を参照してください。

file_loc

検査するLOBのファイル・ロケータ。

pattern

テスト対象のパターン。パターンは、BLOBの場合はRAWバイトのグループ、CLOBの場合は文字列(VARCHAR2)です。パターンの最大サイズは16383バイトです。

offset

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

nth

出現番号。1から始まります。

戻り値

表93-68 INSTRファンクションの戻り値

戻り値 説明

INTEGER

一致したパターンの先頭のオフセット。バイト数または文字数で示されます。

パターンが見つからない場合は0 (ゼロ)が戻されます。

NULL

次のいずれかです。

- INパラメータのいずれか1つ以上がNULLまたはINVALIDの場合

-offset < 1またはoffset > LOBMAXSIZE

-nth < 1

-nth > LOBMAXSIZE

使用上のノート

VARCHAR2バッファ(patternパラメータ)の形式は、CLOBパラメータの形式と一致する必要があります。つまり、入力LOBのパラメータのタイプがNCLOBの場合、バッファにはNCHARデータが含まれる必要があります。これに対して、入力LOBのパラメータのタイプがCLOBの場合、バッファにはCHARデータが含まれる必要があります。

BFILEの場合は、この操作を行う前に、FILEOPEN操作でファイルをあらかじめオープンしておく必要があります。

INSTRなど、パターン・マッチング用にRAWまたはVARCHAR2パラメータを受け入れる操作では、パターン・パラメータまたは副文字列において、正規表現または特殊一致文字(例: SQLのLIKE)はサポートされていません。

例外

表93-69 BFILEに関するINSTRファンクションの例外

例外 説明

UNOPENED_FILE

ファイルが入力ロケータを使用してオープンされていません。

NOEXIST_DIRECTORY

ディレクトリが存在しません。

NOPRIV_DIRECTORY

ディレクトリに対する権限がありません。

INVALID_DIRECTORY

ディレクトリがファイルのオープン後に無効となりました。

INVALID_OPERATION

ファイルが存在しないか、またはファイルのアクセス権限がありません。

BUFFERING_ENABLED

LOBでバッファが有効になっている場合、LOBバッファを有効にした状態では操作を実行できません。

参照:

93.9.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);

パラメータ

表93-70 ISOPENファンクションのパラメータ

パラメータ 説明

lob_loc

LOBロケータ。詳細は、「操作上のノート」を参照してください。

file_loc

ファイル・ロケータ。

戻り値

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

使用上のノート

BFILESの場合、オープンされているかどうかはロケータと関連付けられています。入力ロケータがOPENに渡されていない場合、そのBFILEはこのロケータによってオープンされていないとみなされます。ただし、別のロケータがBFILEをオープンしている可能性はあります。異なるロケータを使用すると、同じBFILE上で複数のOPENを実行できます。

内部LOBの場合、オープンされているかどうかは、ロケータではなくそのLOBに関連付けられています。ロケータ1がLOBをオープンした場合、ロケータ2もそのLOBはオープンしているとみなします。内部LOBの場合は、LOBが実際にオープンしているかどうかを調べるにはサーバー上の状態をチェックするため、ISOPENでラウンドトリップが必要です。

外部LOB(BFILE)の場合も、サーバーに状態が保持されているため、ISOPENでラウンドトリップが必要です。

参照:

このプロシージャの使用方法の詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください。

93.9.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);

パラメータ

表93-71 ISREMOTEファンクションのパラメータ

パラメータ 説明

lob_loc

LOBのロケータ。

戻り値

BOOLEAN: データベース・リンクを介して取得されたリモートLOBの場合はTRUE、ローカル・データベースから取得されたLOBの場合はFALSE

参照:

93.9.34 ISSECUREFILEファンクション

このファンクションは、渡されるLOBロケータがSecurefile LOB用の場合にTRUEを戻します。そうでなければ、FALSEを戻します。

構文

DBMS_LOB ISSECUREFILE(
    lob_loc    IN      BLOB)
  RETURN BOOLEAN;

プラグマ

PRAGMA RESTRICT_REFERENCES(issecurefile, WNDS, RNDS, WNPS, RNPS);

パラメータ

表93-72 ISSECUREFILEファンクションのパラメータ

パラメータ 説明

lob_loc

LOBロケータ。詳細は、「操作上のノート」を参照してください。

戻り値

このファンクションは、渡されるLOBロケータがSecurefile LOB用の場合にTRUEを戻します。そうでなければ、FALSEを戻します。

93.9.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);

パラメータ

表93-73 ISTEMPORARYプロシージャのパラメータ

パラメータ 説明

lob_loc

LOBロケータ。詳細は、「操作上のノート」を参照してください。

戻り値

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

使用上のノート

FREETEMPORARYを指定して一時LOBを解放した場合、LOBロケータはNULLに設定されません。したがって、ISTEMPORARYは、解放後に明示的にNULLに再設定されていないロケータに対して0(ゼロ)を戻します。

参照:

このプロシージャの使用方法の詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください。

93.9.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);

パラメータ

表93-74 LOADBLOBFROMFILEプロシージャのパラメータ

パラメータ 説明

dest_lob

ロード先のBLOBロケータ。

src_bfile

ロード元のBFILEロケータ。

amount

BFILEからロードするバイト数。BFILEの終わりまでロードするDBMS_LOB.LOBMAXSIZEを使用することもできます。

dest_offset

(IN)宛先BLOBの書込み開始位置を示すオフセット(起点: 1) (バイト数で指定します)。(OUT)この書込み終了直後の宛先BLOBの新規オフセット(バイト数で指定します)で、次の書込みの開始位置でもあります。

src_offset

(IN)ソースBFILEの読込み開始位置を示すオフセット(起点: 1)。バイト数で指定します。(OUT)この読込み終了直後のソースBFILEのオフセット。バイト数で示されます。次の読込みの開始位置でもあります。

使用上のノート

  • ソースおよび宛先の両方の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パラメータにデフォルト値を指定します。使用可能な定数およびデフォルトを次に示します。

表93-75 パラメータのデフォルト値

パラメータ デフォルト値 説明

amount

DBMS_LOB.LOBMAXSIZE (IN)

ファイル全体をロードします。

dest_offset

1 (IN)

先頭から開始します。

src_offset

1 (IN)

先頭から開始します。

DBMSLOB.SQLで定義される定数

lobmaxsize                    CONSTANT INTEGER        := DBMS_LOB.LOBMAXSIZE;

例外

表93-76 LOADBLOBFROMFILEプロシージャの例外

例外 説明

VALUE_ERROR

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

INVALID_ARGVAL

次のいずれかです。

- src_offsetまたはdest_offset < 1

- src_offsetまたはdest_offset > LOBMAXSIZE。

- amount < 1。

- amount > LOBMAXSIZE。

BUFFERING_ENABLED

BLOBでバッファが有効になっている場合、LOBバッファを有効にした状態では操作を実行できません。

参照:

このプロシージャの使用方法の詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください。

93.9.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);

パラメータ

表93-77 LOADCLOBFROMFILEプロシージャのパラメータ

パラメータ 説明

dest_lob

ロード先のCLOB/NCLOBロケータ。

src_bfile

ロード元のBFILEロケータ。

amount

BFILEからロードするバイト数。BFILEの終わりまでロードするDBMS_LOB.LOBMAXSIZEを使用することもできます。

dest_offset

(IN)宛先CLOBの書込み開始位置を示すオフセット(起点: 1) (文字数で指定します)。(OUT)このロード終了直後の新規オフセット(文字数で示します)で、次のロード開始位置でもあります。常にロード終了後の最初の完全な文字の開始位置を示します。最後の文字が完全でない場合は、部分文字の先頭までオフセットが戻ります。

src_offset

(IN)ソースBFILEの読込み開始位置を示すオフセット(起点: 1)。バイト数で指定します。(OUT)この読込み終了直後のソースBFILEのオフセット。バイト数で示されます。次の読込みの開始位置でもあります。

bfile_csid

ソース(BFILE)ファイルの文字セットID。

lang_context

(IN)現行のロードに関する、シフト・ステータスなどの言語コンテキスト。

(OUT)現在のロードが停止した時点の言語コンテキストで、同じソースから継続してロードする場合に、次のロードで使用されます。この情報はユーザーに戻されるため、ユーザーは、ソース・データを失ったり誤って解釈することなく、継続してこの情報をロードで使用できます。最初のロードの場合、または特に必要ない場合は、デフォルトの0 (ゼロ)を使用してください。言語コンテキストの詳細は、ユーザーには隠されています。コールするときに、その内容を認識している必要はありません。

warning

(OUT)警告メッセージ。これは、ロード時になんらかの異常が発生したことを示します。ユーザーのミスが原因の場合とそれ以外が原因の場合があります。ロードは要求に応じて完了され、警告メッセージをチェックするかどうかはユーザーが判断します。現在、発生する可能性があるのは、変換不可能な文字に関する警告のみです。これは、ソースの文字が宛先の文字に正しく変換できない場合に発生し、その位置にはデフォルトの置換文字(例: '?')が使用されます。メッセージは、定数値DBMS_LOB.WARN_INCONVERTIBLE_CHARに定義されています。

使用上のノート

ソースおよび宛先の両方の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文字を一連のバイトにマッピングする複数のコード体系が定義されています。表93-78に、このサブプログラムでサポートされているUnicodeコード体系を示します。

表93-78 サポートされているUnicodeコード体系

コード体系 Oracle名 bfile_csid値

UTF-8

AL32UTF8

873

UTF-16BE

AL16UTF16

2000

UTF-16LE

AL16UTF16LE

2002

CESU-8

UTF8

871

UTF-EBCDIC

UTFE

872

UTF-16

UTF16

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にはロードされません。

定数

使用可能な定数およびデフォルト値を次に示します。

表93-79 LOADCLOBFROMFILEパラメータの推奨値

パラメータ 推奨値 説明

amount

DBMS_LOB.LOBMAXSIZE (IN)

ファイル全体をロードします。

dest_offset

1 (IN)

先頭から開始します。

src_offset

1 (IN)

先頭から開始します。

csid

0 (IN)

デフォルトのcsid。宛先のcsidを使用します。

lang_context

0 (IN)

デフォルトの言語コンテキスト。

warning

0 (OUT)

警告メッセージはありません。問題ありません。

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;

例外

表93-80 LOADCLOBFROMFILEプロシージャの例外

例外 説明

VALUE_ERROR

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

INVALID_ARGVAL

次のいずれかです。

- src_offsetまたはdest_offset < 1

- src_offsetまたはdest_offset > LOBMAXSIZE。

- amount < 1。

- amount > LOBMAXSIZE。

BUFFERING_ENABLED

CLOBでバッファが有効になっている場合、LOBバッファを有効にした状態では操作を実行できません。

参照:

このプロシージャの使用方法の詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください。

93.9.38 LOADFROMFILEプロシージャ

この推奨されないプロシージャは、ソース外部LOB (BFILE)の全体または一部を宛先内部LOBにコピーします。

ノート:

Oracle Database 12cリリース12.2から、このプロシージャは非推奨になっています。

構文

DBMS_LOB.LOADFROMFILE (
   dest_lob    IN OUT NOCOPY BLOB, 
   src_file    IN            BFILE, 
   amount      IN            INTEGER, 
   dest_offset IN            INTEGER  := 1, 
   src_offset  IN            INTEGER  := 1);

パラメータ

表93-81 LOADFROMFILEプロシージャのパラメータ

パラメータ 説明

dest_lob

ロード先のLOBロケータ。

src_file

ロード元のBFILEロケータ。

amount

BFILEからロードするバイト数。

dest_offset

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

src_offset

ソースBFILEのロード開始位置を示すオフセット(起点: 1)。バイト数で指定します。

使用上のノート

ソースおよび宛先の両方のLOBに対するオフセット、およびソースBFILEからコピーするバイト数を指定できます。amountおよびsrc_offsetは、BFILEを参照するためにバイト単位ですが、dest_offsetはBLOBの場合はバイト単位、CLOBsの場合は文字単位です。

ノート:

入力BFILEは、このプロシージャを使用する前にオープンしている必要があります。バイナリBFILEデータがCLOBにロードされる場合、文字セット変換は暗黙的には実行されません。BFILEデータは、データベース内のCLOBと同じ文字セットであることが必要です。これを検証するためのエラー・チェックは実行されません。

宛先LOBに指定したオフセットが、現在そのLOBに格納されているデータの終わりを超えている場合は、宛先BLOBまたはCLOBに、0(ゼロ)バイトのFILLERまたは空白がそれぞれ挿入されます。オフセットが宛先LOBの現行の長さより小さい場合、既存のデータは上書きされます。

入力amountおよびoffsetを加算した値がBFILE内のデータの長さを超えた場合はエラーが発生します。

ノート:

UTF-8のように文字セットの幅が変化する場合、LOB値は固定幅形式のUCS2で格納されます。したがって、DBMS_LOB.LOADFROMFILEを使用している場合、BFILEのデータはUTF-8文字セットではなくUCS2文字セットにする必要があります。ただし、sql*loaderでは必要な文字セット変換が提供されるため、CLOBまたはNCLOBにデータをロードするには、LOADFROMFILEではなくsql*loaderを使用してください。

オープン/クローズ・インタフェース内のLOB操作のラップは必須ではありません。操作を実行する前にLOBをオープンしなかった場合、LOB列のファンクション索引およびドメイン索引は、コール中に更新されます。ただし、操作を実行する前にLOBをオープンした場合は、トランザクションのコミットを実行する前にクローズする必要があります。内部LOBがクローズされるときに、LOB列のファンクション索引およびドメイン索引が更新されます。

オープン/クローズAPI内のLOB操作をラップしなかった場合、ファンクション索引およびドメイン索引はLOBへ書き込むたびに更新されます。これにより、パフォーマンスに悪影響を及ぼす可能性があります。したがって、LOBへの書込み操作をOPENまたはCLOSE文の中に囲むことをお薦めします。

例外

表93-82 LOADFROMFILEプロシージャの例外

例外 説明

VALUE_ERROR

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

INVALID_ARGVAL

次のいずれかです。

- src_offsetまたはdest_offset < 1

- src_offsetまたはdest_offset > LOBMAXSIZE。

- amount < 1。

- amount > LOBMAXSIZE。

参照:

このプロシージャの使用方法の詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください。

93.9.39 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);

パラメータ

表93-83 MOVE_TO_DBFS_LINKプロシージャのパラメータ

パラメータ 説明

lob_loc

アーカイブされるLOB。

storage_path

LOBが格納されるパス。

flags

DBFS_LINK_CACHEまたはDBFS_LINK_NOCACHE。DBFS_LINK_CACHEが指定されている場合、LOBデータはDBFSストアに書き込まれると同時に、引き続きRDBMSに格納されます。DBFS_LINK_NOCACHEは、LOBデータがDBFSへの書込み後にRDBMSから削除されるように指定します。

例外

表93-84 MOVE_TO_DBFS_LINKプロシージャの例外

例外 説明

SECUREFILE_BADLOB

lob_locはSECUREFILEではありません。

使用上のノート

  • このプロシージャは、LOBがすでにアーカイブされている場合、正常にアーカイブされたときと同様の結果を戻します。その場合、DBFS_LINK_NOCACHEが指定されているか、flagsがデフォルト設定されていると、LOBデータはRDBMSから削除されます。

  • 同じLOBで同じフラグを使用してこのプロシージャを複数回コールしても、効果はありません。

  • すでにアーカイブされているLOBでこのプロシージャをコールすると、フラグの設定に応じてLOBのキャッシュ(DBFS_LINK_CACHE)または削除(DBFS_LINK_NOCACHE)が実行されます。

93.9.40 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);

パラメータ

表93-85 OPENプロシージャのパラメータ

パラメータ 説明

lob_loc

LOBロケータ。詳細は、「操作上のノート」を参照してください。

open_mode

オープンするモード。

BLOBおよびCLOBタイプの場合、モードはLOB_READONLYまたはLOB_READWRITEのいずれかに指定できます。

BFILEタイプの場合、モードはFILE_READONLYである必要があります。

使用上のノート

ノート:

LOBが読取り専用モードでオープンされた場合は、そのLOBに書込みを行おうとすると、エラーが戻されます。BFILEは、読取り専用モードでのみオープンできます。

OPENでは、内部または外部LOBのいずれの場合もサーバーへのラウンドトリップが必要です。内部LOBの場合、OPENはOPENコールに依存しているその他のコードのトリガーとなります。外部LOB (BFILE)の場合、OPENではサーバー側の実際のオペレーティング・システム・ファイルがオープンされるため、ラウンドトリップが必要です。

オープン/クローズ・インタフェース内のすべてのLOB操作のラップは必須ではありません。ただし、LOBをオープンしている場合は、トランザクションのコミットを実行する前にクローズする必要があり、クローズしない場合は、エラーが発生します。内部LOBがクローズされるときに、LOB列のファンクション索引およびドメイン索引が更新されます。

トランザクションによってオープンされたすべてのLOBをクローズする前にトランザクションをコミットすると、エラーが発生します。エラーが戻された場合、LOBのオープンは廃棄されますが、トランザクションのコミットは正常に行われます。したがって、そのトランザクションにおけるLOBおよび非LOBデータの変更はすべてコミットされますが、ドメイン索引およびファンクションベースの索引は更新されません。このような場合は、LOB列のファンクション索引およびドメイン索引を再構築する必要があります。

参照:

このプロシージャの使用方法の詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください。

93.9.41 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);

パラメータ

表93-86 READプロシージャのパラメータ

パラメータ 説明

lob_loc

読み込むLOBのロケータ。詳細は、「操作上のノート」を参照してください。

file_loc

検査するLOBのファイル・ロケータ。

amount

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

offset

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

buffer

読取り操作用の出力バッファ。

例外

表93-87に、すべてのLOBインスタンスに該当する例外を示します。表93-88に、BFILEのみに該当する例外を示します。

表93-87 READプロシージャの例外

例外 説明

VALUE_ERROR

lob_loc、amountまたはoffsetパラメータのいずれかがNULLです。

INVALID_ARGVAL

次のいずれかです。

- amount < 1。

- amount > 32767バイト(またはそれに相当する文字数)

- offset < 1

- offset > LOBMAXSIZE

- amount(バイト数または文字数)がbufferの容量を超えています。

NO_DATA_FOUND

LOBの終わりに達し、LOBから読み込むバイトまたは文字がありません。amountの値は0(ゼロ)です。

表93-88 BFILEに関するREADプロシージャの例外

例外 説明

UNOPENED_FILE

ファイルが入力ロケータを使用してオープンされていません。

NOEXIST_DIRECTORY

ディレクトリが存在しません。

NOPRIV_DIRECTORY

ディレクトリに対する権限がありません。

INVALID_DIRECTORY

ディレクトリがファイルのオープン後に無効となりました。

INVALID_OPERATION

ファイルが存在しないか、またはファイルのアクセス権限がありません。

BUFFERING_ENABLED

LOBでバッファが有効になっている場合、LOBバッファを有効にした状態では操作を実行できません。

使用上のノート

  • VARCHAR2バッファの形式は、CLOBパラメータの形式と一致する必要があります。つまり、入力LOBのパラメータのタイプがNCLOBの場合、バッファにはNCHARデータが含まれる必要があります。これに対して、入力LOBのパラメータのタイプがCLOBの場合、バッファにはCHARデータが含まれる必要があります。

  • クライアントからDBMS_LOB.READをコールすると(SQL*Plus内からのBEGIN/ENDブロックでのコールなど)、戻されるバッファにはクライアントの文字セットのデータが含まれます。データベースは、バッファをユーザーに戻す前に、サーバーの文字セットからクライアントの文字セットにLOB値を変換します。

  • READは、読取り前に必要に応じてLOBを取得します。

  • LOBがDBFSリンクの場合、データは、可能な場合はDBFSからストリーミングされ、可能でない場合は例外が発生します。

参照:

このプロシージャの使用方法の詳細は、『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』を参照してください。

93.9.42 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));

パラメータ

表93-89 SET_DBFS_LINKプロシージャのパラメータ

パラメータ 説明

lob_loc

参照値を格納するLOB。

archive_id

いずれかのGET_DBFS_LINKファンクションをコールすると戻されるアーカイブID。

例外

表93-90 SET_DBFS_LINKプロシージャの例外

例外 説明

SECUREFILE_BADLOB

lob_locはSECUREFILEではありません。

93.9.43 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);

パラメータ

表93-91 SETCONTENTTYPEプロシージャのパラメータ

パラメータ 説明

lob_loc

コンテンツ・タイプを割り当てるLOB。

contenttype

割り当てる文字列。

例外

表93-92 SETCONTENTTYPEプロシージャの例外

例外 説明

SECUREFILE_BADLOB

lob_locはSECUREFILEではありません。

使用上のノート

SECUREFILEに関連付けられている既存のコンテンツ・タイプをクリアするには、contenttypeを空の文字列に設定してSETCONTENTTYPEを起動します。

93.9.44 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);

パラメータ

表93-93 SETOPTIONSプロシージャのパラメータ

パラメータ 説明

lob_loc

検査するLOBのロケータ。詳細は、「操作上のノート」を参照してください。

option_type

表93-2を参照してください

options

表93-3を参照してください。

例外

表93-94 SETOPTIONSプロシージャの例外

例外 説明

SECUREFILE_BADLOB

操作に対してサポートされていないオブジェクト・タイプ。

INVALID_ARGVAL

パラメータ値が無効でした。

QUERY_WRITE

問合せ時に操作を実行できません。

BUFFERING_ENABLED

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

使用上のノート

  • DBMS_LOB.SETOPTIONSを使用して、個々のLOBに対する暗号化を使用可能または使用禁止にすることはできません。

  • 表の作成時に圧縮または重複除外の機能が設定されていない場合、これらの機能をSecureFile列に対してオンまたはオフにすることはできません。

    GETOPTIONSファンクションとSETOPTIONSプロシージャは、個々のSecureFileに対して動作します。特定のSecureFile LOBに対する圧縮または重複除外をオフにしたり、SETOPTIONSによってすでにオフにされている場合はオンにすることができます。

  • このコールでは、変更を永続化させる際にサーバーへのラウンドトリップが発生します。

93.9.45 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);

パラメータ

表93-95 SUBSTRファンクションのパラメータ

パラメータ 説明

lob_loc

読み込むLOBのロケータ。詳細は、「操作上のノート」を参照してください。

file_loc

検査するLOBのファイル・ロケータ。

amount

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

offset

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

戻り値

表93-96 SUBSTRファンクションの戻り値

戻り値 説明

RAW

ファンクション・オーバーロード。パラメータにBLOBまたはBFILEを使用します。

VARCHAR2

CLOBのバージョン。

NULL

次のいずれかです。

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

- amount < 1。

- amount > 32767

- offset < 1

- offset > LOBMAXSIZE

例外

表93-97 BFILE操作に関するSUBSTRファンクションの例外

例外 説明

UNOPENED_FILE

ファイルが入力ロケータを使用してオープンされていません。

NOEXIST_DIRECTORY

ディレクトリが存在しません。

NOPRIV_DIRECTORY

ディレクトリに対する権限がありません。

INVALID_DIRECTORY

ディレクトリがファイルのオープン後に無効となりました。

INVALID_OPERATION

ファイルが存在しないか、またはファイルのアクセス権限がありません。

BUFFERING_ENABLED

LOBでバッファが有効になっている場合、LOBバッファを有効にした状態では操作を実行できません。

使用上のノート

  • VARCHAR2バッファの形式は、CLOBパラメータの形式と一致する必要があります。つまり、入力LOBのパラメータのタイプがNCLOBの場合、バッファにはNCHARデータが含まれる必要があります。これに対して、入力LOBのパラメータのタイプがCLOBの場合、バッファにはCHARデータが含まれる必要があります。

  • クライアントからDBMS_LOB.SUBSTRをコールすると(SQL*Plus内からのBEGIN/ENDブロックでのコールなど)、戻されるバッファにはクライアントの文字セットのデータが含まれます。データベースは、バッファをユーザーに戻す前に、サーバーの文字セットからクライアントの文字セットにLOB値を変換します。

  • DBMS_LOB.SUBSTRは、LOBに格納されている文字に基づいて8191個以上の文字を戻します。使用可能なバッファを超える文字バイト数が原因ですべての文字が戻されない場合、新しいオフセットでDBMS_LOB.SUBSTRをコールして残りの文字を読み取るか、すべてのデータを抽出するまでサブプログラムのコールをループする必要があります。

  • SUBSTRは、読取り前に必要に応じてLOBを取得します。

  • LOBがDBFSリンクの場合、データは、可能な場合はDBFSからストリーミングされ、可能でない場合は例外が発生します。

参照:

93.9.46 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);

パラメータ

表93-98 TRIMプロシージャのパラメータ

パラメータ 説明

lob_loc

長さを切り捨てる内部LOBのロケータ。詳細は、「操作上のノート」を参照してください。

newlen

切り捨て後の新しいLOB値の長さ。BLOBの場合はバイト数、CLOBの場合は文字数で指定します。

例外

表93-99 TRIMプロシージャの例外

例外 説明

VALUE_ERROR

lob_locがNULLです。

INVALID_ARGVAL

次のいずれかです。

- new_len < 0

- new_len > LOBMAXSIZE

QUERY_WRITE

問合せまたはPDMLパラレル実行サーバー内でLOB書込みが実行できません。

BUFFERING_ENABLED

LOBでバッファが有効になっている場合、LOBバッファを有効にした状態では操作を実行できません。

使用上のノート

  • オープン/クローズ・インタフェース内のLOB操作のラップは必須ではありません。操作を実行する前にLOBをオープンしなかった場合、LOB列のファンクション索引およびドメイン索引は、コール中に更新されます。ただし、操作を実行する前にLOBをオープンした場合は、トランザクションのコミットを実行する前にクローズする必要があります。内部LOBがクローズされるときに、LOB列のファンクション索引およびドメイン索引が更新されます。

  • オープン/クローズAPI内のLOB操作をラップしなかった場合、ファンクション索引およびドメイン索引はLOBへ書き込むたびに更新されます。これにより、パフォーマンスに悪影響を及ぼす可能性があります。したがって、LOBへの書込み操作をOPENまたはCLOSE文の中に囲むことをお薦めします。

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

参照:

93.9.47 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);

パラメータ

表93-100 WRITEプロシージャのパラメータ

パラメータ 説明

lob_loc

書込み先の内部LOBのロケータ。詳細は、「操作上のノート」を参照してください。

amount

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

offset

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

buffer

書込み用の入力バッファ。

例外

表93-101 WRITEプロシージャの例外

例外 説明

VALUE_ERROR

lob_loc、amountまたはoffsetパラメータのいずれかがNULL、範囲外またはINVALIDです。

INVALID_ARGVAL

次のいずれかです。

- amount < 1。

- amount > 32767バイト(またはそれに相当する文字数)

- offset < 1

- offset > LOBMAXSIZE

QUERY_WRITE

問合せまたはPDMLパラレル実行サーバー内でLOB書込みが実行できません。

BUFFERING_ENABLED

LOBでバッファが有効になっている場合、LOBバッファを有効にした状態では操作を実行できません。

SECUREFILE_OUTOFBOUNDS

FRAGMENT_*が設定されている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全体を上書きするように指定されている場合を除きます。

参照:

93.9.48 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);

パラメータ

表93-102 WRITEAPPENDプロシージャのパラメータ

パラメータ 説明

lob_loc

書込み先の内部LOBのロケータ。詳細は、「操作上のノート」を参照してください。

amount

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

buffer

書込み用の入力バッファ。

使用上のノート

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

例外

表93-103 WRITEAPPENDプロシージャの例外

例外 説明

VALUE_ERROR

lob_loc、amountまたはoffsetパラメータのいずれかがNULL、範囲外またはINVALIDです。

INVALID_ARGVAL

次のいずれかです。

- amount < 1。

- amount > 32767バイト(またはそれに相当する文字数)

QUERY_WRITE

問合せまたはPDMLパラレル実行サーバー内でLOB書込みが実行できません。

BUFFERING_ENABLED

LOBでバッファが有効になっている場合、LOBバッファを有効にした状態では操作を実行できません。

使用上のノート

  • VARCHAR2バッファの形式は、CLOBパラメータの形式と一致する必要があります。つまり、入力LOBのパラメータのタイプがNCLOBの場合、バッファにはNCHARデータが含まれる必要があります。これに対して、入力LOBのパラメータのタイプがCLOBの場合、バッファにはCHARデータが含まれる必要があります。

  • クライアントからDBMS_LOB.WRITEAPPENDをコールするとき(SQL*Plus内からのBEGIN/ENDブロックでのコールなど)は、バッファにクライアントの文字セットのデータが含まれている必要があります。データベースは、バッファ・データをLOBに書き込む前に、クライアント側の文字セットをサーバー側の文字セットに変換します。

  • オープン/クローズ・インタフェース内のLOB操作のラップは必須ではありません。操作を実行する前にLOBをオープンしなかった場合、LOB列のファンクション索引およびドメイン索引は、コール中に更新されます。ただし、操作を実行する前にLOBをオープンした場合は、トランザクションのコミットを実行する前にクローズする必要があります。内部LOBがクローズされるときに、LOB列のファンクション索引およびドメイン索引が更新されます。

  • オープン/クローズAPI内のLOB操作をラップしなかった場合、ファンクション索引およびドメイン索引はLOBへ書き込むたびに更新されます。これにより、パフォーマンスに悪影響を及ぼす可能性があります。したがって、LOBへの書込み操作をOPENまたはCLOSE文の中に囲むことをお薦めします。

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

参照: