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

戻る
戻る
 
次へ
次へ
 

69 DBMS_LOB

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


関連項目:

『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』

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


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 SecureFilesおよびラージ・オブジェクト開発者ガイド』および『Oracle Database SQL言語リファレンス』のBFILENAMEファンクションに関する項を参照してください。

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


定数

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

表69-1 DBMS_LOBの定数

定数 定義

FILE_READONLY

CONSTANT BINARY_INTEGER := 0;

LOB_READONLY

CONSTANT BINARY_INTEGER := 0;

LOB_READWRITE

CONSTANT BINARY_INTEGER := 1;

LOBMAXSIZE

CONSTANT INTEGER := 18446744073709551615;

SESSION

CONSTANT PLS_INTEGER := 10;

CALL

CONSTANT PLS_INTEGER := 12;


表69-2 DBMS_LOBのオプション・タイプ

定数 定義

OPT_COMPRESS

CONSTANT BINARY_INTEGER := 1;

OPT_ENCRYPT

CONSTANT BINARY_INTEGER := 2;

OPT_DEDUPLICATE

CONSTANT BINARY_INTEGER := 4;


表69-3 DBMS_LOBのオプション値

定数 定義

COMPRESS_OFF

CONSTANT BINARY_INTEGER := 0;

COMPRESS_ON

CONSTANT BINARY_INTEGER := 1;

ENCRYPT_OFF

CONSTANT BINARY_INTEGER := 0;

ENCRYPT_ON

CONSTANT BINARY_INTEGER := 2;

DEDUPLICATE_OFF

CONSTANT BINARY_INTEGER := 0;

DEDUPLICATE_ON

CONSTANT PLS_INTEGER := 4;



データ型

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

表69-4 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の最大サイズは、LOB列が存在する表領域のブロック・サイズの232-1(4294967295)倍と等しくなります。これによって、最大LOBサイズの範囲は8TBから128TBまでとなります。

最大バッファ・サイズ

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


使用上の注意

すべてのDBMS_LOBサブプログラムは、LOBロケータをベースにして動作します。 DBMS_LOBサブプログラムを正常に実行するためには、データベース表領域または外部ファイル・システムにすでに存在しているLOBを示す入力ロケータを用意する必要があります。 『Oracle Database SecureFilesおよびラージ・オブジェクト開発者ガイド』の第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 SecureFilesおよびラージ・オブジェクト開発者ガイド』の外部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. DBMS_LOBのすべてのファンクションは、入力パラメータのいずれかがNULLの場合、NULLを戻します。 LOBロケータがNULLとして入力されると、DBMS_LOBのすべてのプロシージャで例外が発生します。

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

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


関連項目:

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


例外

表69-5 DBMS_LOBの例外

例外 コード 説明

ACCESS_ERROR

22925

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

BUFFERING_ENABLED

22279

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

INVALID_ARGVAL

21560

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

INVALID_DIRECTORY

22287

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

NO_DATA_FOUND


ループ読取り操作用の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_*操作を実行しようとしました。

SECUREFILE_WRONGTYPE

43854

SECUREFILE LOBとともにのみ使用可能なサブプログラム内でBASICFILE LOBが使用されました。

UNOPENED_FILE

22289

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

VALUE_ERROR

6502

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



DBMS_LOBサブプログラムの要約

表69-6 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プロシージャ


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

FRAGMENT_DELETEプロシージャ


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

FRAGMENT_INSERTプロシージャ


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

FRAGMENT_MOVEプロシージャ


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

FRAGMENT_REPLACEプロシージャ


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

FREETEMPORARYプロシージャ


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

GETCHUNKSIZEファンクション


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

GETLENGTHファンクション


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

GETOPTIONSファンクション


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

GET_STORAGE_LIMITファンクション


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

INSTRファンクション


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

ISOPENファンクション


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

ISTEMPORARYファンクション


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

LOADBLOBFROMFILEプロシージャ


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

LOADCLOBFROMFILEプロシージャ


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

LOADFROMFILEプロシージャ


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

OPENプロシージャ


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

READプロシージャ


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

SETOPTIONSプロシージャ


LOB単位でCSCE機能を使用可能にして、デフォルトの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);

パラメータ

表69-7 APPENDプロシージャのパラメータ

パラメータ 説明

dest_lob

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

src_lob

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


例外

表69-8 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文の中に囲むことをお薦めします。


関連項目:

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


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

パラメータ

表69-9 CLOSEプロシージャのパラメータ

パラメータ 説明

lob_loc

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


例外

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

使用上の注意

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

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

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


関連項目:

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


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

パラメータ

表69-10 COMPAREファンクションのパラメータ

パラメータ 説明

lob_1

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

lob_2

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

amount

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

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の指定が(DBMS_LOB.LOBMAXSIZE/n)を超えると、(DBMS_LOB.LOBMAXSIZE/n)またはMax(length(clob1), length(clob2))のサイズのうち、小さい方の範囲で文字を比較します。

例外

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

例外 説明

UNOPENED_FILE

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

NOEXIST_DIRECTORY

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

NOPRIV_DIRECTORY

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

INVALID_DIRECTORY

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

INVALID_OPERATION

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

BUFFERING_ENABLED

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



関連項目:

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


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

パラメータ

表69-12 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パラメータに変数または値を渡す必要があります。

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

表69-13 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を指定します。

例外

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

表69-14 CONVERTTOBLOBプロシージャの例外

例外 説明

VALUE_ERROR

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

INVALID_ARGVAL

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

- src_offsetまたはdest_offset < 1

- src_offsetまたはdest_offset > LOBMAXSIZE

- amount < 1

- amount > LOBMAXSIZE



関連項目:

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


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

パラメータ

表69-15 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パラメータに変数または値を渡す必要があります。

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

表69-16 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パラメータで、ソース・データのキャラクタ・セットを指定する必要があります。blob_csidには0の値を渡せます。これを行う場合、データベースではBLOB内の文字データが宛先CLOBと同じキャラクタ・セットであると想定されます。

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

例外

表69-17 CONVERTTOCLOBプロシージャの例外

例外 説明

VALUE_ERROR

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

INVALID_ARGVAL

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

- src_offsetまたはdest_offset < 1

- src_offsetまたはdest_offset > LOBMAXSIZE

- amount < 1

- amount > LOBMAXSIZE



関連項目:

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


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

パラメータ

表69-18 COPYプロシージャのパラメータ

パラメータ 説明

dest_lob

コピー先のLOBロケータ。

src_lob

コピー元のLOBロケータ。

amount

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

dest_offset

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

src_offset

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


例外

表69-19 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文の中に囲むことをお薦めします。


関連項目:

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


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

パラメータ

表69-20 CREATETEMPORARYプロシージャのパラメータ

パラメータ 説明

lob_loc

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

cache

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

dur

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

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



関連項目:

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

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

パラメータ

表69-21 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パラメータに戻されます。

例外

表69-22 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文の中に囲むことをお薦めします。


関連項目:

  • 「TRIMプロシージャ」

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



FILECLOSEプロシージャ

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


注意:

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

構文

DBMS_LOB.FILECLOSE (
    file_loc IN OUT NOCOPY BFILE);

パラメータ

表69-23 FILECLOSEプロシージャのパラメータ

パラメータ 説明

file_loc

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


例外

表69-24 FILECLOSEプロシージャの例外

例外 説明

VALUE_ERROR

file_locの入力値がNULLです。

UNOPENED_FILE

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

NOEXIST_DIRECTORY

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

NOPRIV_DIRECTORY

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

INVALID_DIRECTORY

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

INVALID_OPERATION

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



関連項目:



FILECLOSEALLプロシージャ

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

構文

DBMS_LOB.FILECLOSEALL;

例外

表69-25 FILECLOSEALLプロシージャの例外

例外 説明

UNOPENED_FILE

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



関連項目:



FILEEXISTSファンクション

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

構文

DBMS_LOB.FILEEXISTS (
   file_loc     IN    BFILE)
  RETURN INTEGER;

プラグマ

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

パラメータ

表69-26 FILEEXISTSファンクションのパラメータ

パラメータ 説明

file_loc

BFILEのロケータ。


戻り値

表69-27 FILEEXISTSファンクションの戻り値

戻り値 説明

0

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

1

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


例外

表69-28 FILEEXISTSファンクションの例外

例外 説明

NOEXIST_DIRECTORY

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

NOPRIV_DIRECTORY

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

INVALID_DIRECTORY

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



関連項目:

  • 「FILEISOPENファンクション」

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



FILEGETNAMEプロシージャ

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

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

構文

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

パラメータ

表69-29 FILEGETNAMEプロシージャのパラメータ

パラメータ 説明

file_loc

BFILEのロケータ。

dir_alias

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

filename

BFILE


例外

表69-30 FILEGETNAMEプロシージャの例外

例外 説明

VALUE_ERROR

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

INVALID_ARGVAL

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



関連項目:

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


FILEISOPENファンクション

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

構文

DBMS_LOB.FILEISOPEN (
   file_loc   IN    BFILE)
  RETURN INTEGER;

プラグマ

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

パラメータ

表69-31 FILEISOPENファンクションのパラメータ

パラメータ 説明

file_loc

BFILEのロケータ。


戻り値

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

使用上の注意

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

例外

表69-32 FILEISOPENファンクションの例外

例外 説明

NOEXIST_DIRECTORY

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

NOPRIV_DIRECTORY

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

INVALID_DIRECTORY

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



関連項目:

  • 「FILEEXISTSファンクション」

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



FILEOPENプロシージャ

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

構文

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

パラメータ

表69-33 FILEOPENプロシージャのパラメータ

パラメータ 説明

file_loc

BFILEのロケータ。

open_mode

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


例外

表69-34 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

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



関連項目:



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

パラメータ

表69-35 FRAGMENT_DELETEプロシージャのパラメータ

パラメータ 説明

lob_loc

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

amount

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

offset

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


例外

表69-36 FRAGMENT_DELETEプロシージャの例外

例外 説明

SECUREFILE_BADLOB

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

INVALID_ARGVAL

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

QUERY_WRITE

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

BUFFERING_ENABLED

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

SECUREFILE_BADLOB

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

SECUREFILE_OUTOFBOUNDS

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

SECUREFILE_WRONGTYPE

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



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

パラメータ

表69-37 FRAGMENT_INSERTプロシージャのパラメータ

パラメータ 説明

lob_loc

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

amount

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

offset

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

buffer

LOBに挿入するデータ。


例外

表69-38 FRAGMENT_INSERTプロシージャの例外

例外 説明

SECUREFILE_BADLOB

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

INVALID_ARGVAL

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

QUERY_WRITE

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

BUFFERING_ENABLED

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

SECUREFILE_BADLOB

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

SECUREFILE_OUTOFBOUNDS

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

SECUREFILE_WRONGTYPE

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



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

パラメータ

表69-39 FRAGMENT_MOVEプロシージャのパラメータ

パラメータ 説明

lob_loc

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

amount

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

src_offset

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

dest_offset

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


例外

表69-40 FRAGMENT_MOVEプロシージャの例外

例外 説明

SECUREFILE_BADLOB

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

INVALID_ARGVAL

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

QUERY_WRITE

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

BUFFERING_ENABLED

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

SECUREFILE_BADLOB

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

SECUREFILE_OUTOFBOUNDS

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

SECUREFILE_WRONGTYPE

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


使用上の注意


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

パラメータ

表69-41 FRAGMENT_REPLACEプロシージャのパラメータ

パラメータ 説明

lob_loc

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

old_amount

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

new_amount

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

offset

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

buffer

LOBに挿入するデータ。


例外

表69-42 FRAGMENT_REPLACEプロシージャの例外

例外 説明

SECUREFILE_BADLOB

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

INVALID_ARGVAL

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

QUERY_WRITE

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

BUFFERING_ENABLED

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

SECUREFILE_BADLOB

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

SECUREFILE_OUTOFBOUNDS

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

SECUREFILE_WRONGTYPE

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


使用上の注意

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


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

パラメータ

表69-43 FREETEMPORARYプロシージャのパラメータ

パラメータ 説明

lob_loc

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


使用上の注意


関連項目:

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


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

パラメータ

表69-44 GET_STORAGE_LIMITファンクションのパラメータ

パラメータ 説明

lob_loc

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


戻り値

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

使用上の注意


関連項目:

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


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

パラメータ

表69-45 GETCHUNKSIZEファンクションのパラメータ

パラメータ 説明

lob_loc

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


戻り値

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

使用上の注意

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

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


関連項目:

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

例外

表69-46 GETCHUNKSIZEプロシージャの例外

例外 説明

BUFFERING_ENABLED

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



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

パラメータ

表69-47 GETLENGTHファンクションのパラメータ

パラメータ 説明

file_loc

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


戻り値

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

例外

表69-48 GETLENGHTHプロシージャの例外

例外 説明

BUFFERING_ENABLED

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



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 HARACTER SET ANY_CS,
  option_types        IN     PLS_INTEGER)
RETURN PLS_INTEGER;

パラメータ

表69-49 GETOPTIONSファンクションのパラメータ

パラメータ 説明

lob_loc

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

option_type

「DBMS_LOBのオプション・タイプ」を参照してください。


戻り値

戻り値は、渡されるオプション・タイプ(「DBMS_LOBのオプション・タイプ」を参照)に応じて、COMPRESS_ONENCRYPT_ONおよびDEDUPLICATE_ON「DBMS_LOBのオプション値」を参照)の組合せになります。

例外

表69-50 GETOPTIONSファンクションの例外

例外 説明

SECUREFILE_BADLOB

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

INVALID_ARGVAL

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

QUERY_WRITE

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

BUFFERING_ENABLED

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

SECUREFILE_BADLOB

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

SECUREFILE_WRONGTYPE

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



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

パラメータ

表69-51 INSTRファンクションのパラメータ

パラメータ 説明

lob_loc

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

file_loc

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

pattern

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

offset

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

nth

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


戻り値

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

例外

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

例外 説明

UNOPENED_FILE

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

NOEXIST_DIRECTORY

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

NOPRIV_DIRECTORY

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

INVALID_DIRECTORY

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

INVALID_OPERATION

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

BUFFERING_ENABLED

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



関連項目:

  • 「SUBSTRファンクション」

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



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

パラメータ

表69-54 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およびラージ・オブジェクト開発者ガイド』を参照してください。


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

パラメータ

表69-55 ISTEMPORARYファンクションのパラメータ

パラメータ 説明

lob_loc

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


戻り値

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


関連項目:

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


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

パラメータ

表69-56 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文の中に囲むことをお薦めします。

定数およびデフォルト

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

表69-57 パラメータのデフォルト値

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

amount

DBMS_LOB.LOBMAXSIZE (IN)

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

dest_offset

1(IN)

先頭から開始します。

src_offset

1(IN)

先頭から開始します。


DBMSLOB.SQLで定義される定数

lobmaxsize                    CONSTANT INTEGER        := DBMS_LOB.LOBMAXSIZE;

例外

表69-58 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およびラージ・オブジェクト開発者ガイド』を参照してください。


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

パラメータ

表69-59 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の場合を除きます)。

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

ソースBFILEには、Unicodeキャラクタ・セットのデータを含めることができます。Unicode標準では、Unicode文字を一連のバイトにマッピングする複数のコード体系が定義されています。表69-60「サポートされているUnicodeコード体系」に、このサブプログラムでサポートされているUnicodeコード体系を示します。

表69-60 サポートされている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にはロードされません。

定数

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

表69-61 パラメータのデフォルト値

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

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;

例外

表69-62 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およびラージ・オブジェクト開発者ガイド』を参照してください。


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

パラメータ

表69-63 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の場合はバイト単位、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は、必要なキャラクタ・セット変換を提供します。

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

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

例外

表69-64 LOADFROMFILEプロシージャの例外

例外 説明

VALUE_ERROR

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

INVALID_ARGVAL

次のいずれかです。

- src_offsetまたはdest_offset < 1

- src_offsetまたはdest_offset > LOBMAXSIZE

- amount < 1

- amount > LOBMAXSIZE



関連項目:

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


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

パラメータ

表69-65 OPENプロシージャのパラメータ

パラメータ 説明

lob_loc

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

open_mode

オープンするモード。

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

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


使用上の注意


注意:

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

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

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

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


関連項目:

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


READプロシージャ

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

実際に読み込まれたバイト数または文字数は、amountパラメータに戻されます。 入力offsetLOBの終わりを超えた位置を指している場合、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);

パラメータ

表69-66 READプロシージャのパラメータ

パラメータ 説明

lob_loc

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

file_loc

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

amount

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

offset

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

buffer

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


例外

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

表69-67 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(ゼロ)です。


表69-68 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値を変換します。


関連項目:

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


SETOPTIONSプロシージャ

このプロシージャは、LOB単位でCSCE機能を使用可能/使用禁止にして、デフォルトの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);

パラメータ

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

パラメータ 説明

lob_loc

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

option_type

「DBMS_LOBのオプション・タイプ」を参照してください。

options

「DBMS_LOBのオプション値」を参照してください。


例外

表69-70 SETOPTIONSプロシージャの例外

例外 説明

SECUREFILE_BADLOB

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

INVALID_ARGVAL

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

QUERY_WRITE

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

BUFFERING_ENABLED

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

SECUREFILE_WRONGTYPE

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


使用上の注意

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


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

パラメータ

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

パラメータ 説明

lob_loc

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

file_loc

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

amount

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

offset

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


戻り値

表69-72 SUBSTRファンクションの戻り値

戻り値 説明

RAW

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

VARCHAR2

CLOBのバージョン。

NULL

次のいずれかです。

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

- amount < 1

- amount > 32767

- offset < 1

- offset > LOBMAXSIZE


例外

表69-73 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値を変換します。


関連項目:



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

パラメータ

表69-74 TRIMプロシージャのパラメータ

パラメータ 説明

lob_loc

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

newlen

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


例外

表69-75 TRIMプロシージャの例外

例外 説明

VALUE_ERROR

lob_locNULLです。

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文の中に囲むことをお薦めします。


関連項目:



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

パラメータ

表69-76 WRITEプロシージャのパラメータ

パラメータ 説明

lob_loc

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

amount

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

offset

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

buffer

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


例外

表69-77 WRITEプロシージャの例外

例外 説明

VALUE_ERROR

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

INVALID_ARGVAL

次のいずれかです。

- amount < 1

- amount > MAXBUFSIZE

- 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文の中に囲むことをお薦めします。


関連項目:



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

パラメータ

表69-78 WRITEAPPENDプロシージャのパラメータ

パラメータ 説明

lob_loc

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

amount

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

buffer

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


使用上の注意

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

例外

表69-79 WRITEAPPENDプロシージャの例外

例外 説明

VALUE_ERROR

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

INVALID_ARGVAL

次のいずれかです。

- amount < 1

- amount > MAXBUFSIZE

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文の中に囲むことをお薦めします。


関連項目: