ヘッダーをスキップ
Oracle Database PL/SQLパッケージ・プロシージャおよびタイプ・リファレンス
10g リリース2(10.2)
B19245-02
  目次
目次
索引
索引

戻る
戻る
 
次へ
次へ
 

52 DBMS_LOB

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


関連項目:

『Oracle Databaseアプリケーション開発者ガイド-ラージ・オブジェクト』

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


DBMS_LOBの使用方法


概要

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


セキュリティ・モデル

このパッケージは、SYSの下に作成する必要があります。このパッケージが提供する操作は、パッケージ所有者SYSではなく、現行のコール・ユーザーのもとで実行されます。

無名PL/SQLブロックからコールされたDBMS_LOBサブプログラムは、カレント・ユーザーの権限を使用して実行されます。ストアド・プロシージャからコールされたDBMS_LOBサブプログラムは、そのストアド・プロシージャの所有者の権限を使用して実行されます。

ユーザーはプロシージャの作成時に、AUTHIDを設定して定義者の権限または実行者の権限のどちらを使用するのかを指示できます。次に例を示します。

CREATE PROCEDURE proc1 authid definer ...

または

CREATE PROCEDURE proc1 authid current_user ...

関連項目:

AUTHIDおよび権限の詳細は、『Oracle Database PL/SQLユーザーズ・ガイドおよびリファレンス』を参照してください。

DIRECTORY機能を使用すると、BFILEに安全にアクセスできます。この機能については、『Oracle Databaseアプリケーション開発者ガイド-ラージ・オブジェクト』および『Oracle Database SQLリファレンス』のBFILENAMEファンクションに関する項を参照してください。

一時LOBに関係するセキュリティ・モデルについては「使用上の注意」を参照してください。


定数

DBMS_LOBでは、次の定数が定義されます。

file_readonly CONSTANT BINARY_INTEGER := 0;
lob_readonly  CONSTANT BINARY_INTEGER := 0;
lob_readwrite CONSTANT BINARY_INTEGER := 1;
lobmaxsize    CONSTANT INTEGER        := 18446744073709551615;
call          CONSTANT PLS_INTEGER    := 12;
session       CONSTANT PLS_INTEGER    := 10;

データ型

DBMS_LOBパッケージでは、表52-1に示すデータ型が使用されます。

表52-1 DBMS_LOBで使用されるデータ型

説明

BLOB

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

RAW

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

CLOB

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

VARCHAR2

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

INTEGER

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

BFILE

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


DBMS_LOBパッケージでは特別な型を定義しません。

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

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


ルールおよび制限

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

外部ファイル(BFILE)に固有のルールと制限


通常、DBMS_LOBを使用してPL/SQLブロック内でオープンされたファイルは、ブロックの正常終了または異常終了の前にクローズしてください。

最大LOBサイズ

データベースでサポートされるLOBの最大サイズはdb_block_size初期化パラメータの値に値4294967295をかけた結果に等しくなります。これによって、最大LOBサイズの範囲は8TBから128TBまでとなります。

最大バッファ・サイズ

最大バッファ・サイズの32767バイトはmaxbufsizeによって表します。


使用上の注意

すべてのDBMS_LOBサブプログラムは、LOBロケータをベースにして動作します。DBMS_LOBサブプログラムを正常に実行するためには、データベース表領域または外部ファイル・システムにすでに存在しているLOBを示す入力ロケータを用意する必要があります。 『Oracle Databaseアプリケーション開発者ガイド-ラージ・オブジェクト』の第1章も参照してください。

データベースでLOBを使用するには、最初にSQLデータ定義言語(DDL)を使用して、LOB列が含まれる表を定義する必要があります。

内部LOB

表にLOB列を定義した後、表に内部LOBを移入するには、SQLデータ操作言語(DML)を使用して、LOB列のロケータを初期化するか、または移入します。

外部LOB

外部LOB(BFILE)がLOBロケータで示されるようにするには、次のことを実行する必要があります。

これらの作業が終了すると、指定されたLOBロケータを使用して、LOB列が含まれている行を挿入または更新できます。

LOBの定義および作成が終了すると、SELECTを実行してLOBロケータをローカルのPL/SQL LOB変数に割り当て、この変数をDBMS_LOBの入力パラメータとして使用してLOB値にアクセスできます。

これらの作業を行うための別の方法の詳細は、『Oracle Databaseアプリケーション開発者ガイド-ラージ・オブジェクト』の外部LOB(BFILE)へのアクセスに関する項を参照してください。

一時LOB

データベースでは、一時LOBの定義、作成、削除、アクセスおよび更新がサポートされています。一時LOBデータは、ユーザーの一時表領域に格納されています。一時LOBはデータベースに永続的には格納されません。この目的は、主にLOBデータの変換の実行です。

一時LOBの場合は、OCI、PL/SQLまたはその他のプログラム・インタフェースを使用して作成または操作する必要があります。一時LOBは、BLOBCLOBまたはNCLOBのいずれにもできます。

一時LOBは空の状態で作成されます。デフォルトでは一時LOBは、それが作成されたセッションの終了時にすべて削除されます。処理が途中で停止したり、データベースがクラッシュした場合、一時LOBは削除され、その領域は解放されます。

一時LOBを論理バケットにまとめてグループ化するインタフェースもあります。一時LOB用のこの論理記憶域は期間で表されます。各一時LOBには、CACHE/ NOCACHEなど、別々の記憶特性があります。セッションごとにデフォルトの記憶域があり、ユーザーが特定の期間を指定しない場合、一時LOBはこの記憶域に格納されます。さらに、期間ごとに解放操作を実行して、期間内のすべてのコンテンツを解放できます。

一時LOBに関する、読込み一貫性(CR)、取消し、バックアップ、パラレル処理またはトランザクション管理はサポートされていません。一時LOBには、CRおよびロールバックがサポートされていないため、エラーが発生した場合、ユーザーは一時LOBを解放して、最初から操作をやり直す必要があります。

CR、取消しおよびバージョンが、一時LOBに対しては生成されないため、同じ一時LOBに複数のロケータを割り当てると、パフォーマンスに影響する可能性があります。具体的には、各ロケータが一時LOBの独自のコピーを所有するためです。

別のロケータが一時LOBを指しているときに、その内容を変更する場合は、一時LOBのコピーが作成されます。この場合、変更操作が行われたロケータは、一時LOBの新しいコピーを指します。これ以降、他のロケータは、変更操作が行われたロケータと同じデータは参照しません。このような状況の場合、永続LOBでディープ・コピーは行われません。これは、CRスナップショットおよびバージョン・ページによって、ユーザーは独自のバージョンのLOBを簡単に参照できるためです。

必要な場合は、OCIのロケータへのポインタを使用し、ロケータへの複数のポインタが同じ一時LOBロケータを指すように設定することによって、擬似REF構文を取得できます。PL/SQLでは、1つの一時LOBに対して複数のロケータは使用しないでください。一時LOBロケータは、参照によって別のプロシージャに渡される可能性があります。

一時LOBは表スキーマと関連付けられていないため、行内および行外の一時LOBという概念はありません。ユーザーが一時LOBインスタンスを作成すると、エンジンによってLOBデータへのロケータが作成され戻されます。PL/SQLのDBMS_LOBパッケージ、PRO*C、OCIおよびその他のプログラム・インタフェースは、このロケータを介して、永続LOBに対する操作と同様に一時LOBを操作します。

クライアント側の一時LOBはサポートされていません。一時LOBはすべてサーバーに常駐します。

一時LOBは、永続LOBがサポートしているEMPTY_BLOBまたはEMPTY_CLOBファンクションをサポートしません。EMPTY_BLOBファンクションは、LOBの初期化を指定しますが、データの移入は行いません。

一時LOBインスタンスは、適切なFREETEMPORARYまたはOCIDurationEnd文でOCIまたはDBMS_LOBパッケージを使用したときのみ破棄できます。

一時LOBインスタンスは、適切なOCIおよびDBMS_LOB文を使用することによって、標準の永続内部LOBと同様にアクセスおよび変更できます。一時LOBを永続LOBに変更するには、OCIまたはDBMS_LOBCOPYコマンドを明示的に使用して、一時LOBを永続LOBにコピーする必要があります。

セキュリティは、LOBロケータを介して提供されます。一時LOBは、その作成ユーザーのみ参照できます。ロケータは、あるユーザーのセッションから別のユーザーのセッションに渡すことはできません。あるセッションから別のセッションにロケータを渡しても、元のセッションの一時LOBにはアクセスできません。一時LOB参照は、各ユーザー固有のセッションに限定されます。別の場所のロケータを使用するユーザーは、同じLOB IDを持つ自分のセッション内でのみLOBにアクセスできます。ユーザーがこれを試行することはお薦めしませんが、試行した場合でも他のユーザーのデータに影響を与えることはありません。

データベースは、V$TEMPORARY_LOBSと呼ばれるv$ビューにセッションごとの一時LOBを記録します。この中には、セッションごとに存在している一時LOB数に関する情報が含まれています。V$ビューは、DBAが使用するためのものです。セッションから、データベースはどのユーザーがその一時LOBを所有しているかを判断できます。V$TEMPORARY_LOBSDBA_SEGMENTSと組み合せて使用すると、DBAは、セッションで一時LOB用に使用されている領域の量を把握できます。これらの表を使用すると、DBAは一時LOBが使用している一時領域の緊急クリーンアップを監視して指示できます。

一時LOBに固有の注意事項は次のとおりです。

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

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

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

  4. 一時LOBは値構文に準拠しています。これは、永続LOBとの一貫性を保ち、LOB用のANSI規格に従うためです。このため、OCILobLocatatorAssignまたはPL/SQLで同じ割当てが実行されるたびに、データベースでは一時LOBのコピーが作成されます。

    各ロケータは、それぞれ独自のLOB値を指します。一時LOBを作成するためにあるロケータが使用され、そのロケータが、OCIのOCILobLOcatorAssignを使用して、またはPL/SQLの割当て操作によって別のLOBロケータに割り当てられた場合、データベースは元の一時LOBのコピーを作成し、2番目のロケータがそのコピーを指すようにします。

    複数のユーザーが同じLOBを変更できるようにするには、同じロケータを使用する必要があります。OCIでは、ロケータへのポインタを使用して、そのポインタが同じロケータを指すように割り当てることによって、比較的簡単にこの処理を実行できます。PL/SQLでは、同様の効果を得るには、同じLOB変数を使用してLOBを更新する必要があります。

    次の例は、コピーが作成される場合、または最低1回サーバーへの特別なラウンドトリップが行われる場合を示しています。

    DECLARE
      a blob;
      b blob;
    BEGIN
      dbms_lob.createtemporary(b, TRUE);
      -- the following assignment results in a deep copy
      a := b;
    END;
    
    

    PL/SQLコンパイラは、OUTまたはIN OUTパラメータにバインドされる実引数のテンポラリ・コピーを作成します。実パラメータが一時LOBの場合、テンポラリ・コピーはディープ(値)コピーです。

    次のPL/SQLブロックは、一時LOBIN OUTパラメータとして渡すことによって、ディープ・コピーが行われる例を示しています。

    DECLARE
      a blob;
      procedure foo(parm IN OUT blob) is
      BEGIN
       ...
      END;
    BEGIN
      dbms_lob.createtemporary(a, TRUE);
      -- the following call results in a deep copy of the blob a
      foo(a);
    END;
    
    

    PL/SQLパラメータの受渡しのためのディープ・コピーを最小限にするためには、可能であればNOCOPYのコンパイラ・ヒントを使用します。

    dbms_lob.createtemporary()に渡される継続期間パラメータがヒントです。新しい一時LOBの継続期間は、PL/SQLのロケータ変数の継続期間と同じです。たとえば、前述のプログラム・ブロックでは、プログラム変数aには常駐フレームの継続期間が設定されます。したがって、ブロックの終わりでは、ファンクションの終了時にaのメモリーが解放されます。

    PL/SQLパッケージ変数を使用して一時LOBが作成された場合、SESSIONの継続期間を持つパッケージ変数の継続期間が設定されます。

    BEGIN
       y clob;
      END;
    /
    BEGIN
       dbms_lob.createtemporary(package.y, TRUE);
    END;
    

関連項目:

NOCOPY構文の詳細は、『Oracle Database PL/SQLユーザーズ・ガイドおよびリファレンス』を参照してください。


例外

表52-2 DBMS_LOBの例外

例外 コード 説明

INVALID_ARGVAL

21560

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

ACCESS_ERROR

22925

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

NOEXIST_DIRECTORY

22285

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

NOPRIV_DIRECTORY

22286

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

INVALID_DIRECTORY

22287

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

OPERATION_FAILED

22288

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

UNOPENED_FILE

22289

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

OPEN_TOOMANY

22290

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

NO_DATA_FOUND


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

VALUE_ERROR

6502

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



DBMS_LOBサブプログラムの要約

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

サブプログラム 説明

APPENDプロシージャ


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

CLOSEプロシージャ


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

COMPAREファンクション


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

CONVERTTOBLOBプロシージャ


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

CONVERTTOCLOBプロシージャ


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

COPYプロシージャ


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

CREATETEMPORARYプロシージャ


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

ERASEプロシージャ


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

FILECLOSEプロシージャ


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

FILECLOSEALLプロシージャ


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

FILEEXISTSファンクション


ファイルがサーバー上に存在しているかどうかをチェックします。

FILEGETNAMEプロシージャ

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

FILEISOPENファンクション


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

FILEOPENプロシージャ


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

FREETEMPORARYプロシージャ


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

GETCHUNKSIZEファンクション


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

GETLENGTHファンクション


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

GET_STORAGE_LIMIT


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

INSTRファンクション


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

ISOPENファンクション


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

ISTEMPORARYファンクション


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

LOADBLOBFROMFILEプロシージャ


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

LOADCLOBFROMFILEプロシージャ


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

LOADFROMFILEプロシージャ


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

OPENプロシージャ


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

READプロシージャ


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

SUBSTRファンクション


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

TRIMプロシージャ


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

WRITEプロシージャ


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

WRITEAPPENDプロシージャ


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



APPENDプロシージャ

このプロシージャは、ソース内部LOBの内容を宛先LOBに追加します。ソースLOB全体を追加します。

APPENDプロシージャは2種類、オーバーロードされています。

構文

DBMS_LOB.APPEND (
   dest_lob IN OUT  NOCOPY BLOB,
   src_lob  IN             BLOB);

DBMS_LOB.APPEND (
   dest_lob IN OUT  NOCOPY CLOB  CHARACTER SET ANY_CS,
   src_lob  IN             CLOB  CHARACTER SET dest_lob%CHARSET);

パラメータ

表52-4 APPENDプロシージャのパラメータ

パラメータ 説明

dest_lob

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

src_lob

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


例外

表52-5 APPENDプロシージャの例外

例外 説明

VALUE_ERROR

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


使用上の注意

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

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


関連項目:

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


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

パラメータ

表52-6 CLOSEプロシージャのパラメータ

パラメータ 説明

lob_loc

LOBロケータ。詳細は、「使用上の注意」を参照してください。


例外

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

使用上の注意

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

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

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


関連項目:

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


COMPAREファンクション

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

構文

DBMS_LOB.COMPARE (
   lob_1            IN BLOB,
   lob_2            IN BLOB,
   amount           IN INTEGER := 4294967295,
   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 := 4294967295,
   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);

パラメータ

表52-7 COMPAREファンクションのパラメータ

パラメータ 説明

lob_1

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

lob_2

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

amount

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

offset_1

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

offset_2

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


戻り値

使用上の注意

比較できるのは、同じデータ型のLOB(BLOB型のLOBと他のBLOBCLOBCLOBBFILEBFILE)に限られます。BFILEの場合は、この操作を行う前に、FILEOPEN操作でファイルをあらかじめオープンしておく必要があります。

offsetおよびamountパラメータによって指定した範囲のデータがすべて完全に一致すると0(ゼロ)が戻されます。一致しない場合は0(ゼロ)以外のINTEGERが戻されます。

固定幅のnバイトのCLOBの場合は、COMPAREに対する入力amountの指定が(4294967295/n)を超えると、(4294967295/n)またはMax(length(clob1), length(clob2))のサイズのうち、小さい方の範囲で文字を比較します。

例外

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

例外 説明

UNOPENED_FILE

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

NOEXIST_DIRECTORY

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

NOPRIV_DIRECTORY

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

INVALID_DIRECTORY

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

INVALID_OPERATION

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



関連項目:

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


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

パラメータ

表52-9 CONVERTTOBLOBプロシージャのパラメータ

パラメータ 説明

dest_lob

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

src_blob

ソース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プロシージャをコールする前に、次の事前条件を満たしている必要があります。

定数およびデフォルト

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

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

表52-10 DBMS_LOB.CONVERTTOBLOBの一般的な値

パラメータ 説明

amount

LOBMAXSIZE(IN)

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

dest_offset

1(IN)

先頭から開始します。

src_offset

1(IN)

先頭から開始します。

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の値を渡せます。 0の値を渡すと、データベースは目的のキャラクタ・セットがソースLOBのキャラクタ・セットと同じであるとみなしてデータのバイナリ・コピーを実行し、キャラクタ・セットの変換は行いません。

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

例外

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

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

例外 説明

VALUE_ERROR

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

INVALID_ARGVAL

次のいずれかの条件が発生しました。

- src_offsetまたはdest_offset < 1

- src_offsetまたはdest_offset > LOBMAXSIZE

- amount < 1

- amount > LOBMAXSIZE



関連項目:

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


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

パラメータ

表52-12 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プロシージャをコールする前に、次の事前条件を満たしている必要があります。

定数およびデフォルト

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

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

表52-13 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の値を渡せます。0の値を渡すと、データベースは、BLOBが宛先CLOBと同じキャラクタ・セットで文字データを格納しているものとみなし、宛先LOBへのデータのバイナリ・コピーを実行して、キャラクタ・セットの変換は行いません。

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

例外

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

例外 説明

VALUE_ERROR

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

INVALID_ARGVAL

次のいずれかの条件が発生しました。

- src_offsetまたはdest_offset < 1

- src_offsetまたはdest_offset > LOBMAXSIZE

- amount < 1

- amount > LOBMAXSIZE



関連項目:

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


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

パラメータ

表52-15 COPYプロシージャのパラメータ

パラメータ 説明

dest_lob

コピー先のLOBロケータ。

src_lob

コピー元のLOBロケータ。

amount

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

dest_offset

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

src_offset

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


例外

表52-16 COPYプロシージャの例外

例外 説明

VALUE_ERROR

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

INVALID_ARGVAL

次のいずれかです。

- src_offsetまたはdest_offset < 1

- src_offsetまたはdest_offset > LOBMAXSIZE

- amount < 1

- amount > LOBMAXSIZE


使用上の注意

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

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

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

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


関連項目:

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


CREATETEMPORARYプロシージャ

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

構文

DBMS_LOB.CREATETEMPORARY (
   lob_loc IN OUT NOCOPY BLOB,
   cache   IN            BOOLEAN,
   dur     IN            PLS_INTEGER := 10);

DBMS_LOB.CREATETEMPORARY (
   lob_loc IN OUT NOCOPY CLOB CHARACTER SET ANY_CS,
   cache   IN            BOOLEAN,
   dur     IN            PLS_INTEGER := 10);

パラメータ

表52-17 CREATETEMPORARYプロシージャのパラメータ

パラメータ 説明

lob_loc

LOBロケータ。詳細は、「使用上の注意」を参照してください。

cache

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

dur

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

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



関連項目:

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

  • NOCOPY、および一時LOBをパラメータとして渡す方法の詳細は、『Oracle Database PL/SQLユーザーズ・ガイドおよびリファレンス』を参照してください。



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

パラメータ

表52-18 ERASEプロシージャのパラメータ

パラメータ 説明

lob_loc

消去するLOBのロケータ。詳細は「使用上の注意」を参照してください。

amount

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

offset

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


使用上の注意


注意:

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

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

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

例外

表52-19 ERASEプロシージャの例外

例外 説明

VALUE_ERROR

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

INVALID_ARGVAL

次のいずれかです。

- amount < 1またはamount > LOBMAXSIZE

- offset < 1またはoffset > LOBMAXSIZE


使用上の注意

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

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


関連項目:

  • 「TRIMプロシージャ」

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



FILECLOSEプロシージャ

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


注意:

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

構文

DBMS_LOB.FILECLOSE (
    file_loc IN OUT NOCOPY BFILE);

パラメータ

表52-20 FILECLOSEプロシージャのパラメータ

パラメータ 説明

file_loc

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


例外

表52-21 FILECLOSEプロシージャの例外

例外 説明

VALUE_ERROR

file_locの入力値がNULLです。

UNOPENED_FILE

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

NOEXIST_DIRECTORY

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

NOPRIV_DIRECTORY

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

INVALID_DIRECTORY

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

INVALID_OPERATION

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



関連項目:



FILECLOSEALLプロシージャ

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

構文

DBMS_LOB.FILECLOSEALL;

例外

表52-22 FILECLOSEALLプロシージャの例外

例外 説明

UNOPENED_FILE

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



関連項目:



FILEEXISTSファンクション

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

構文

DBMS_LOB.FILEEXISTS (
   file_loc     IN    BFILE)
  RETURN INTEGER;

プラグマ

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

パラメータ

表52-23 FILEEXISTSファンクションのパラメータ

パラメータ 説明

file_loc

BFILEのロケータ。


戻り値

表52-24 FILEEXISTSファンクションの戻り値

戻り値 説明

0

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

1

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


例外

表52-25 FILEEXISTSファンクションの例外

例外 説明

NOEXIST_DIRECTORY

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

NOPRIV_DIRECTORY

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

INVALID_DIRECTORY

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



関連項目:

  • 「FILEISOPENファンクション」

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



FILEGETNAMEプロシージャ

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

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

構文

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

パラメータ

表52-26 FILEGETNAMEプロシージャのパラメータ

パラメータ 説明

file_loc

BFILEのロケータ。

dir_alias

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

filename

BFILE


例外

表52-27 FILEGETNAMEプロシージャの例外

例外 説明

VALUE_ERROR

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

INVALID_ARGVAL

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



関連項目:

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


FILEISOPENファンクション

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

構文

DBMS_LOB.FILEISOPEN (
   file_loc   IN    BFILE)
  RETURN INTEGER;

プラグマ

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

パラメータ

表52-28 FILEISOPENファンクションのパラメータ

パラメータ 説明

file_loc

BFILEのロケータ。


戻り値

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

使用上の注意

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

例外

表52-29 FILEISOPENファンクションの例外

例外 説明

NOEXIST_DIRECTORY

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

NOPRIV_DIRECTORY

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

INVALID_DIRECTORY

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



関連項目:

  • 「FILEEXISTSファンクション」

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



FILEOPENプロシージャ

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

構文

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

パラメータ

表52-30 FILEOPENプロシージャのパラメータ

パラメータ 説明

file_loc

BFILEのロケータ。

open_mode

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


例外

表52-31 FILEOPENプロシージャの例外

例外 説明

VALUE_ERROR

file_locまたはopen_modeNULLです。

INVALID_ARGVAL

open_modeFILE_READONLYではありません。

OPEN_TOOMANY

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

NOEXIST_DIRECTORY

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

INVALID_DIRECTORY

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

INVALID_OPERATION

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



関連項目:



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

パラメータ

表52-32 FREETEMPORARYプロシージャのパラメータ

パラメータ 説明

lob_loc

LOBロケータ。詳細は、「使用上の注意」を参照してください。


使用上の注意

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

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


関連項目:

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


GET_STORAGE_LIMIT

DBMS_LOB.GET_STORAGE_LIMITファンクションは、データベース構成のLOBの記憶域制限を返します。DBMS_LOBパッケージは、この記憶域制限のサイズまでのLOBインスタンスをサポートします。

構文

DBMS_LOB.GET_STORAGE_LIMIT
  RETURN INTEGER;

戻り値

このファンクションから戻される値は、データベース構成のLOBインスタンスの最大許容サイズです。戻り値は、DB_BLOCK_SIZE初期化パラメータの設定によって異なり、DB_BLOCK_SIZE初期化パラメータの値の(4GB-1)倍として計算されます。

使用上の注意

CLOBおよびNCLOBインスタンスは文字数でサイズ計算されますが、BLOBインスタンスはバイト数で計算されることに注意してください。


関連項目:

LOB記憶域制限の詳細は、『Oracle Databaseアプリケーション開発者ガイド-ラージ・オブジェクト』を参照してください。


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

パラメータ

表52-33 GETCHUNKSIZEファンクションのパラメータ

パラメータ 説明

lob_loc

LOBロケータ。詳細は、「使用上の注意」を参照してください。


戻り値

BLOBの場合に戻される値はバイト単位です。CLOBの場合に戻される値は文字単位です。

使用上の注意

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


関連項目:

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


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

パラメータ

表52-34 GETLENGTHファンクションのパラメータ

パラメータ 説明

file_loc

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


戻り値

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


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

パラメータ

表52-35 INSTRファンクションのパラメータ

パラメータ 説明

lob_loc

検査するLOBのロケータ。詳細は、「使用上の注意」を参照してください。

file_loc

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

pattern

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

offset

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

nth

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


戻り値

表52-36 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)はサポートされていません。

例外

表52-37 BFILESに関するINSTRファンクションの例外

例外 説明

UNOPENED_FILE

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

NOEXIST_DIRECTORY

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

NOPRIV_DIRECTORY

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

INVALID_DIRECTORY

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

INVALID_OPERATION

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



関連項目:

  • 「SUBSTRファンクション」

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



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

パラメータ

表52-38 ISOPENファンクションのパラメータ

パラメータ 説明

lob_loc

LOBロケータ。詳細は、「使用上の注意」を参照してください。

file_loc

ファイル・ロケータ。


使用上の注意

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

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

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


関連項目:

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


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

パラメータ

表52-39 ISTEMPORARYプロシージャのパラメータ

パラメータ 説明

lob_loc

LOBロケータ。詳細は、「使用上の注意」を参照してください。


戻り値

ロケータが一時LOBを指している場合は、temporaryにTRUEが戻されます。そうでない場合はFALSEが戻されます。


関連項目:

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


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

パラメータ

表52-40 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_offsetBFILEを参照するため、バイト単位で、dest_offsetBLOBの場合はバイト単位です。

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

入力amountおよびoffsetを加算した値がBFILE内のデータの長さを超えた場合はエラーが発生します(ただし、指定されているamountが、BFILEの終わりに達するまでロードするように指定できるLOBMAXSIZEの場合を除きます)。

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

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

定数およびデフォルト

パラメータを省略する簡単な方法はありません。IN/OUTパラメータに変数を宣言するか、またはINパラメータにデフォルト値を指定します。使用可能な定数およびデフォルトを次に示します。

表52-41 パラメータのデフォルト値

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

amount

DBMSLOB.LOBMAXSIZE(IN)

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

dest_offset

1(IN)

先頭から開始します。

src_offset

1(IN)

先頭から開始します。


DBMSLOB.SQLで定義される定数

lobmaxsize                    CONSTANT INTEGER        := 4294967295;

例外

表52-42 LOADBLOBFROMFILEプロシージャの例外

例外 説明

VALUE_ERROR

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

INVALID_ARGVAL

次のいずれかです。

- src_offsetまたはdest_offset < 1

- src_offsetまたはdest_offset > LOBMAXSIZE

- amount < 1

- amount > LOBMAXSIZE



関連項目:

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


LOADCLOBFROMFILEプロシージャ

このプロシージャは、BFILEのデータを必要なキャラクタ・セット変換を行った後、内部CLOB/NCLOBにロードし、新しいオフセットを戻します。

構文

DBMS_LOB.LOADCLOBFROMFILE (
   dest_lob       IN OUT NOCOPY   BLOB,
   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);

パラメータ

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


使用上の注意

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

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

入力amountおよびoffsetを加算した値がBFILE内のデータの長さを超えた場合はエラーが発生します(ただし、指定されているamountが、BFILEの終わりに達するまでロードするように指定できるLOBMAXSIZEの場合を除きます)。

次の要件に注意してください。

定数

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

表52-44 パラメータのデフォルト値

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

amount

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

例外

表52-45 LOADCLOBFROMFILEプロシージャの例外

例外 説明

VALUE_ERROR

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

INVALID_ARGVAL

次のいずれかです。

- src_offsetまたはdest_offset < 1

- src_offsetまたはdest_offset > LOBMAXSIZE

- amount < 1

- amount > LOBMAXSIZE



関連項目:

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


LOADFROMFILEプロシージャ

このプロシージャは、ソース外部LOBBFILE)の全体または一部を宛先内部LOBにコピーします。

構文

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

パラメータ

表52-46 LOADFROMFILEプロシージャのパラメータ

パラメータ 説明

dest_lob

ロード先のLOBロケータ。

src_file

ロード元のBFILEロケータ。

amount

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

dest_offset

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

src_offset

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


使用上の注意

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


注意:

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

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

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


注意:

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

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

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

例外

表52-47 LOADFROMFILEプロシージャの例外

例外 説明

VALUE_ERROR

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

INVALID_ARGVAL

次のいずれかです。

- src_offsetまたはdest_offset < 1

- src_offsetまたはdest_offset > LOBMAXSIZE

- amount < 1

- amount > LOBMAXSIZE



関連項目:

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


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

パラメータ

表52-48 OPENプロシージャのパラメータ

パラメータ 説明

lob_loc

LOBロケータ。詳細は、「使用上の注意」を参照してください。

open_mode

オープンするモード。

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

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


使用上の注意


注意:

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

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

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

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


関連項目:

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


READプロシージャ

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

実際に読み込まれたバイト数または文字数は、amountパラメータに戻されます。入力offsetLOBの終わりを超えた位置を指している場合、amountは0(ゼロ)に設定され、NO_DATA_FOUND例外が発生します。

構文

DBMS_LOB.READ (
   lob_loc   IN             BLOB,
   amount    IN OUT  NOCOPY BINARY_INTEGER,
   offset    IN             INTEGER,
   buffer    OUT            RAW);

DBMS_LOB.READ (
   lob_loc   IN             CLOB CHARACTER SET ANY_CS,
   amount    IN OUT  NOCOPY BINARY_INTEGER,
   offset    IN             INTEGER,
   buffer    OUT            VARCHAR2 CHARACTER SET lob_loc%CHARSET);

DBMS_LOB.READ (
   file_loc   IN              BFILE,
   amount    IN OUT   NOCOPY BINARY_INTEGER,
   offset    IN              INTEGER,
   buffer    OUT             RAW);

パラメータ

表52-49 READプロシージャのパラメータ

パラメータ 説明

lob_loc

読み込むLOBのロケータ。詳細は、「使用上の注意」を参照してください。

file_loc

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

amount

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

offset

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

buffer

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


例外

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

表52-50 READプロシージャの例外

例外 説明

VALUE_ERROR

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

INVALID_ARGVAL

次のいずれかです。

- amount < 1

- amount > MAXBUFSIZE

- offset < 1

- offset > LOBMAXSIZE

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

NO_DATA_FOUND

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


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

例外 説明

UNOPENED_FILE

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

NOEXIST_DIRECTORY

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

NOPRIV_DIRECTORY

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

INVALID_DIRECTORY

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

INVALID_OPERATION

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


使用上の注意

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

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


関連項目:

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


SUBSTRファンクション

このファンクションは、LOBの先頭からの絶対offsetから開始し、LOBamountバイトまたは文字を戻します。

固定幅のnバイトのCLOBの場合、SUBSTRに対する入力amountが(32767/n)を超えると、長さ(32767/n)の文字バッファまたはCLOBの長さのうち、いずれか小さい方が戻されます。可変幅キャラクタ・セットのCLOBの場合、nはCLOBの文字に使用される最大バイト幅です。

構文

DBMS_LOB.SUBSTR (
   lob_loc     IN    BLOB,
   amount      IN    INTEGER := 32767,
   offset      IN    INTEGER := 1)
  RETURN RAW;

DBMS_LOB.SUBSTR (
   lob_loc     IN    CLOB   CHARACTER SET ANY_CS,
   amount      IN    INTEGER := 32767,
   offset      IN    INTEGER := 1)
  RETURN VARCHAR2 CHARACTER SET lob_loc%CHARSET;

DBMS_LOB.SUBSTR (
   file_loc     IN    BFILE,
   amount      IN    INTEGER := 32767,
   offset      IN    INTEGER := 1)
  RETURN RAW;

プラグマ

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

パラメータ

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

パラメータ 説明

lob_loc

読み込むLOBのロケータ。詳細は、「使用上の注意」を参照してください。

file_loc

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

amount

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

offset

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


戻り値

表52-53 SUBSTRファンクションの戻り値

戻り値 説明

RAW

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

VARCHAR2

CLOBのバージョン。

NULL

次のいずれかです。

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

- amount < 1

- amount > 32767

- offset < 1

- offset > LOBMAXSIZE


例外

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

例外 説明

UNOPENED_FILE

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

NOEXIST_DIRECTORY

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

NOPRIV_DIRECTORY

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

INVALID_DIRECTORY

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

INVALID_OPERATION

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


使用上の注意

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

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


関連項目:



TRIMプロシージャ

このプロシージャは、内部LOBの値をnewlenパラメータで指定された長さに切り捨てます。BLOBの場合はバイト数、CLOBの場合は文字数で長さを指定します。


注意:

TRIMプロシージャは、LOBの長さをnewlenパラメータで指定された値に減らします。

空のLOBに対してTRIMを実行すると、何も処理は行われずエラーは戻されません。newlenで指定した新しい長さがLOBのサイズよりも大きい場合は、例外が発生します。

構文

DBMS_LOB.TRIM (
   lob_loc        IN OUT  NOCOPY BLOB,
   newlen         IN             INTEGER);

DBMS_LOB.TRIM (
   lob_loc        IN OUT  NOCOPY CLOB CHARACTER SET ANY_CS,
   newlen         IN             INTEGER);

パラメータ

表52-55 RIMプロシージャのパラメータ

パラメータ 説明

lob_loc

長さを切り捨てる内部LOBのロケータ。詳細は、「使用上の注意」を参照してください。

newlen

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


例外

表52-56 TRIMプロシージャの例外

例外 説明

VALUE_ERROR

lob_locNULLです。

INVALID_ARGVAL

次のいずれかです。

- new_len < 0

- new_len > LOBMAXSIZE


使用上の注意

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

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


関連項目:



WRITEプロシージャ

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

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

構文

DBMS_LOB.WRITE (
   lob_loc  IN OUT NOCOPY  BLOB,
   amount   IN             BINARY_INTEGER,
   offset   IN             INTEGER,
   buffer   IN             RAW);

DBMS_LOB.WRITE (
   lob_loc  IN OUT  NOCOPY CLOB   CHARACTER SET ANY_CS,
   amount   IN             BINARY_INTEGER,
   offset   IN             INTEGER,
   buffer   IN             VARCHAR2 CHARACTER SET lob_loc%CHARSET);

パラメータ

表52-57 WRITEプロシージャのパラメータ

パラメータ 説明

lob_loc

書込み先の内部LOBのロケータ。詳細は、「使用上の注意」を参照してください。

amount

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

offset

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

buffer

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


例外

表52-58 WRITEプロシージャの例外

例外 説明

VALUE_ERROR

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

INVALID_ARGVAL

次のいずれかです。

- amount < 1

- amount > MAXBUFSIZE

- offset < 1

- offset > LOBMAXSIZE


使用上の注意

入力amountがバッファのデータより多い場合はエラーが発生します。入力amountがバッファのデータより少ない場合は、バッファからその量のバイト数または文字数のみLOBに書き込まれます。指定したオフセットが現在そのLOBに格納されているデータの終わりを超えている場合は、BLOBまたはCLOBに、0(ゼロ)バイトのFILLERまたは空白がそれぞれ挿入されます。

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

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

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

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


関連項目:



WRITEAPPENDプロシージャ

このプロシージャは、指定された量のデータを内部LOBの後ろに書き込みます。データは、bufferパラメータから書き込まれます。

構文

DBMS_LOB.WRITEAPPEND (
   lob_loc IN OUT NOCOPY BLOB,
   amount  IN            BINARY_INTEGER,
   buffer  IN            RAW);

DBMS_LOB.WRITEAPPEND (
   lob_loc IN OUT NOCOPY CLOB CHARACTER SET ANY_CS,
   amount  IN            BINARY_INTEGER,
   buffer  IN            VARCHAR2 CHARACTER SET lob_loc%CHARSET);

パラメータ

表52-59 WRITEAPPENDプロシージャのパラメータ

パラメータ 説明

lob_loc

書込み先の内部LOBのロケータ。詳細は、「使用上の注意」を参照してください。

amount

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

buffer

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


使用上の注意

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

例外

表52-60 WRITEAPPENDプロシージャの例外

例外 説明

VALUE_ERROR

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

INVALID_ARGVAL

次のいずれかです。

- amount < 1

- amount > MAXBUFSIZE


使用上の注意

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

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

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

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


関連項目: