1. Database SecureFilesおよびラージ・オブジェクト開発者ガイド
  2. 参照セマンティクスLOB
  3. BFILE操作用のLOB API

11 BFILE操作用のLOB API

BFILEを使用する操作用のAPIを、表11-1に示します。

操作ごとに次の項目について説明します。

  • 「使用上のノート」では、特定のプログラム環境またはデータ型に固有の情報など、実装に関するガイドラインを示します。

  • 「構文」では、サポートされているプログラム環境ごとに構文の参照先マニュアルを示します。

  • 「例」では、サンプルの実行に必要な設定タスクについて説明します。掲載されているデモ・ファイルは、$ORACLE_HOME/rdbms/demo/lobs/のplsql、oci、vbおよびjavaという名前のサブディレクトリにあります。ドライバ・プログラムlobdemo.sqlは/plsqlにあり、ドライバ・プログラムlobdemo.cは/ociにあります。

    ノート:

    LOB APIでは、BFILEへのデータのロードはサポートされません。

    関連項目:

    BFILEにデータをロードする方法の詳細は、「SQL*Loaderを使用したLOBのロード」を参照してください。

内容は次のとおりです。

11.1 BFILE APIについてサポートされている環境

表11-1に、APIに対してサポートされているプログラム環境を示します。第1列は、APIで実行される操作を示します。その他の列は、そのAPIがPL/SQL、OCI、COBOL、Pro*C/C++およびJDBCでサポートされているかどうかに応じて、「はい」または「いいえ」となっています。

表11-1 BFILE APIについてサポートされている環境

操作 PL/SQL OCI COBOL Pro*C/C++ JDBC

BFILEを含む行の挿入について

はい

はい

はい

はい

はい

BFILEデータを使用したLOBのロードについて

はい

はい

はい

はい

はい

FILEOPENを使用したBFILEのオープンについて

はい

はい

いいえ

いいえ

はい

OPENを使用したBFILEのオープンについて

はい

はい

はい

はい

はい

ISOPENを使用した、BFILEがオープンしているかどうかの確認について

はい

はい

はい

はい

はい

FILEISOPENを使用した、BFILEがオープンしているかどうかの確認について

はい

はい

いいえ

いいえ

はい

BFILEデータの表示について

はい

はい

はい

はい

はい

BFILEからのデータの読取りについて

はい

はい

はい

はい

はい

SUBSTRを使用した、BFILEデータの一部の読取りについて

はい

いいえ

はい

はい

はい

2つのBFILEの全体または一部の比較

はい

いいえ

はい

はい

はい

INSTRを使用した、BFILEにパターンが存在するかどうかの確認

はい

いいえ

はい

はい

はい

BFILEが存在するかどうかの確認

はい

はい

はい

はい

はい

BFILEの長さの取得

はい

はい

はい

はい

はい

BFILEロケータの割当てについて

はい

はい

はい

はい

はい

BFILEのディレクトリ・オブジェクト名とファイル名の取得

はい

はい

はい

はい

はい

初期化したBFILEロケータを使用したBFILEの更新について

はい

はい

はい

はい

はい

FILECLOSEを使用したBFILEのクローズ

はい

はい

いいえ

いいえ

はい

CLOSEを使用したBFILEのクローズ

はい

はい

はい

はい

はい

FILECLOSEALLを使用したオープン中のすべてのBFILEのクローズ

はい

はい

はい

はい

はい

11.2 BFILEへのアクセスについて

BFILEにアクセスするには、次のインタフェースのいずれかを使用します。

  • OCI(Oracle Call Interface)

  • PL/SQL(DBMS_LOBパッケージ)

  • Pro*C/C++やPro*COBOLなどのプリコンパイラ

  • Java (JDBC)

関連項目:

BFILEへのアクセス用にサポートされている環境の詳細は、「LOB APIの概要」を参照してください。

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

ディレクトリ・オブジェクトを使用すると、BFILEデータ型のアクセスと使用方法を管理できます。

ディレクトリ・オブジェクトには、アクセスするファイルがあるデータベース・サーバー・ファイルシステム上の物理ディレクトリの論理的な別名を指定します。サーバーのファイルシステム内にあるファイルへは、ディレクトリ・オブジェクトに対する必要なアクセス権限が付与されている場合にかぎり、アクセスできます。Oracle Enterprise Manager Cloud Controlを使用してディレクトリ・オブジェクトを管理することもできます。

関連項目:

11.3.1 BFILEロケータの初期化

ディレクトリ・オブジェクトを使用すると、ファイルの位置を柔軟に扱えるようになり、アプリケーション内の物理ファイルの絶対パス名をハードコードしなくてもすみます。

ディレクトリ・オブジェクト名は、BFILEロケータの初期化の際に、BFILENAMEファンクション(SQLおよびPL/SQL)またはOCILobFileSetName()(OCI)で使用されます。

警告:

データベースは、指定したディレクトリおよびパス名が実際に存在するかどうかは検証しません。ご使用のオペレーティング・システムで有効なディレクトリを指定するよう注意してください。オペレーティング・システムでパス名の大文字と小文字が区別される場合は、必ず正しい形式でディレクトリを指定してください。最後のスラッシュを指定する必要はありません(たとえば、/tmp/ではなく、/tmpでもかまいません)。

ディレクトリの指定時には、「..」をパス内に含めることはできません(たとえば、/abc/def/hij..のようには指定できません)。

11.3.2 BFILEへのオペレーティング・システム・ファイルの対応付け

オペレーティング・システムファイルをBFILEに対応付けるために、まずオペレーティング・システム・ファイルへのフルパス名の別名であるディレクトリ・オブジェクトを作成する必要があります。

既存のオペレーティング・システム・ファイルを特定の表の関連するデータベース・レコードに対応付けるには、OracleのSQL DMLを使用します。次に例を示します。

  • BFILEの列がサーバーのファイルシステム内の既存ファイルを参照するようにBFILEを初期化するには、INSERTを使用します。

  • BFILEの参照ターゲットを変更するには、UPDATEを使用します。

  • BFILENAMEファンクションを使用して、BFILEをNULLに初期化してから、後でオペレーティング・システム・ファイルを参照するように更新します。

  • OCIユーザーの場合、OCILobFileSetName()を使用して、INSERT文のVALUES句で使用されるBFILEロケータ変数を初期化することもできます。

ディレクトリの例

次の文では、ファイルImage1.gifおよびimage2.gifをそれぞれkey_valueが21および22のレコードに対応付けます。IMGは、Image1.gifおよびimage2.gifが格納される物理ディレクトリを示すディレクトリ・オブジェクトです。

次のようなデータ構造を設定しないと機能しない場合もあります。

CREATE TABLE Lob_table (
   Key_value NUMBER NOT NULL,
   F_lob BFILE)
   INSERT INTO Lob_table VALUES
      (21,  BFILENAME('IMG', 'Image1.gif'));
   INSERT INTO Lob_table VALUES
      (22, BFILENAME('IMG', 'image2.gif'));

次のUPDATE文は、key_valueが22の行の場合にターゲット・ファイルをimage3.gifに変更します。 

   UPDATE Lob_table SET f_lob = BFILENAME('IMG', 'image3.gif') 
       WHERE Key_value = 22;

警告:

データベースは、ディレクトリ・オブジェクトで指定された環境変数、またはBFILEロケータのファイル名を拡張しません。たとえば、次のように指定するとします。 

BFILENAME('WORK_DIR', '$MY_FILE')

MY_FILEは、オペレーティング・システムで定義された環境変数であり、無効です。

11.4 BFILENAMEと初期化

BFILENAMEは、BFILE列が外部ファイルを参照するようにBFILEを初期化するために使用する組込みファンクションです。

SQL DMLを使用して物理ファイルがレコードに対応付けられると、BFILEに対するその後の読取り操作は、PL/SQLのDBMS_LOBパッケージおよびOCIを使用して実行できます。ただし、これらのファイルは、BFILEを介してアクセスされる場合は読取り専用であるため、BFILEによる更新または削除はできません。

BFILEは参照セマンティクスであるため、同一レコード内または異なるレコード内に、同じファイルを参照する複数のBFILE列を持つことができます。たとえば、次のUPDATE文は、lob_table内でkey_valueが21の行を持つBFILEが、key_valueが22の行と同じファイルを参照するように設定します。 

UPDATE lob_table 
   SET f_lob = (SELECT f_lob FROM lob_table WHERE key_value = 22)
      WHERE key_value = 21;

初期化という点からBFILENAMEを考えてみます。このファンクションは、次の値を初期化できます。

  • BFILE列

  • PL/SQLモジュール内で宣言されるBFILE(自動)変数

11.5 BFILEデータ型の特性

BFILEデータ型を使用すると次のメリットがあります。

  • 特定のBFILEが、一時的に、操作中のモジュール内にかぎり必要な場合、データベース内の列に対応付けることなく、BFILE関連のAPIを変数に対して使用できます。

  • サーバー側の表にBFILE列を作成し、列の値を初期化した後、SELECTを使用してその列の値を取り出す必要がないため、サーバーへのラウンドトリップの必要がなくなります。

DBMS_LOB.LOADFROMFILEに関連する例については、「BFILEデータを使用したLOBのロードについて」を参照してください。

OCIでBFILENAMEに相当するものはOCILobFileSetName()であり、同様に使用できます。

11.5.1 ディレクトリ名の指定

ディレクトリを作成するには、CREATE ANY DIRECTORYシステム権限が必要です。

パス名に2つのピリオド(「..」)を含めることはできません。ディレクトリ・オブジェクトのネーミング規則は、表および索引のネーミング規則と同じです。つまり、通常の識別子は大文字で解釈されますが、デリミタ付き識別子はそのまま解釈されます。たとえば、次のような文があるとします。 

CREATE OR REPLACE DIRECTORY scott_dir AS '/usr/home/scott';

この文は、「SCOTT_DIR」という名前(大文字)のディレクトリ・オブジェクトを作成または再定義します。ただし、次の文のように、ディレクトリ名にデリミタ付き識別子が使用されるとします。 

CREATE DIRECTORY "Mary_Dir" AS '/usr/home/mary';

ディレクトリ・オブジェクトの名前は「Mary_Dir」になります。BFILENAMEをコールするときは、「SCOTT_DIR」および「Mary_Dir」を使用します。次に例を示します。 

BFILENAME('SCOTT_DIR', 'afile')
BFILENAME('Mary_Dir', 'afile')
11.5.1.1 Windowsプラットフォームの場合

Windowsプラットフォーム上では、ディレクトリ名の大/小文字が区別されません。したがって、次の2つの文は同じディレクトリを表します。

CREATE DIRECTORY "big_cap_dir" AS "g:\data\source";

CREATE DIRECTORY "small_cap_dir" AS "G:\DATA\SOURCE";

11.6 BFILEセキュリティ

BFILEセキュリティは、BFILEセキュリティ・モデルおよびそれに対応付けられたSQL文に関連しています。BFILEセキュリティに関係する主なSQL文は、次のとおりです。

  • SQL DDL: ディレクトリ・オブジェクトのCREATEおよびREPLACEまたはALTER

  • SQL DML: ディレクトリ・オブジェクトに対するREADシステム権限およびオブジェクト権限のGRANTおよびREVOKE

11.6.1 所有権および権限

ディレクトリ・オブジェクトは、システム所有のオブジェクトです。

システム所有のオブジェクトの詳細は、『Oracle Database SQL言語リファレンス』を参照してください。Oracle Databaseでは、次の2つの新しいシステム権限をサポートしており、これらはDBAのみに付与されます。

  • CREATE ANY DIRECTORY: ディレクトリ・オブジェクトの作成または変更用

  • DROP ANY DIRECTORY: ディレクトリ・オブジェクトの削除用

11.6.2 ディレクトリ・オブジェクトに対する読取り権限

ディレクトリ・オブジェクトに対するREAD権限によって、そのディレクトリ下に置かれたファイルを読み取ることができます。ディレクトリ・オブジェクトの作成者には、READ権限が自動的に付与されます。

GRANTオプション付きのREAD権限を付与されている場合は、その権限を他のユーザーやロールに付与して、自分の権限ドメインに追加することもできます。

ノート:

READ権限は、個々のファイルではなくディレクトリ・オブジェクトのみに定義されます。したがって、同じディレクトリ内のファイルに異なる権限を割り当てることはできません。

表される物理ディレクトリは、Oracleサーバー・プロセスに必要な、対応するオペレーティング・システム権限(この場合は読取り権限)が含まれていない場合もあります。

DBAは、次のことを確認する必要があります。

  • 物理ディレクトリの存在

  • ファイル、ディレクトリ、ディレクトリへのパスで、Oracleサーバー・プロセスに対する読取り権限が有効であること

  • データベース・ユーザーがファイルにアクセスする間は終始、ディレクトリが使用可能な状態であり、読取り権限も有効であること

ここでの権限とは、単にOracleサーバーがそのディレクトリ内のファイルを読むことができるということです。これらの権限は、実際のファイル操作時に、PL/SQLのDBMS_LOBパッケージおよびOCI APIによってチェックおよび施行されます。

警告:

CREATE ANY DIRECTORY権限およびDROP ANY DIRECTORY権限によって、サーバーのファイルシステムがすべてのデータベース・ユーザーに公開される可能性があるため、DBAは、セキュリティ違反を防止するため、一般のデータベース・ユーザーに対するこれらの権限の付与は慎重に行う必要があります。

11.6.3 BFILEセキュリティ用のSQL DDL

関連項目:

ディレクトリ・オブジェクトを作成、置換、削除する次のSQL DDL文の詳細は、Oracle Database SQL言語リファレンスを参照してください。

  • CREATE DIRECTORY

  • DROP DIRECTORY

11.6.4 BFILEセキュリティ用のSQL DML

関連項目:

BFILEに対してセキュリティを提供する次のSQL DML文の詳細は、Oracle Database SQL言語リファレンスを参照してください。

  • GRANT (システム権限)

  • GRANT (オブジェクト権限)

  • REVOKE (システム権限)

  • REVOKE (オブジェクト権限)

  • AUDIT (新規文)

  • AUDIT (スキーマ・オブジェクト)

11.6.5 ディレクトリのカタログ・ビュー

カタログ・ビューは、ディレクトリ・オブジェクト用に提供され、これによってユーザーは、オブジェクトの名前、および対応するパスおよび権限を参照できます。サポートされるビューは次のとおりです。

  • ALL_DIRECTORIES(OWNER、DIRECTORY_NAME、DIRECTORY_PATH)

    このビューには、ユーザーがアクセスできるすべてのディレクトリが記述されます。

  • DBA_DIRECTORIES(OWNER、DIRECTORY_NAME、DIRECTORY_PATH)

    このビューには、データベース全体について指定されたすべてのディレクトリが記述されます。

11.6.6 ディレクトリ・オブジェクト使用のガイドライン

ディレクトリ機能の主な目的は、サーバーのファイルシステム内の大きなファイルへのアクセスをDBAが管理するうえで、単純で柔軟性があり、既存アプリケーションの変更が不要で、安全性の高いメカニズムを使用可能にすることです。ただし、この目的を実現するには、DBAがディレクトリ・オブジェクトの使用時に次のガイドラインに従うことが非常に重要です。

  • ディレクトリ・オブジェクトは、データファイルのディレクトリにマップしないでください。ディレクトリ・オブジェクトは、Oracleデータファイル、制御ファイル、ログ・ファイルおよび他のシステム・ファイルを含む物理ディレクトリにマップしないでください。これらのファイルを(不意にまたはなんらかの理由で)変更すると、データベースまたはサーバーのオペレーティング・システムが破損する場合があります。

  • DBAのみがシステム権限を持つ必要があります。CREATE ANY DIRECTORYなどのシステム権限(DBAにあらかじめ付与される)を他のユーザーに付与する場合は、慎重に行ってください。多くの場合、データベース管理者のみが、これらの権限を持ちます。

  • DIRECTORY権限を付与するときには、十分な注意が必要です。ディレクトリ・オブジェクトへの権限を他のユーザーに付与する場合は、注意が必要です。同様に、権限をユーザーに付与するときは、WITH GRANT OPTION句の使用にも注意が必要です。

  • データベースの運用中に、ディレクトリ・オブジェクトを削除または置換しないでください。ディレクトリ・オブジェクトは、安易な判断でデータベース運用中に削除または置換しないようにします。ディレクトリ・オブジェクトを削除または置換した場合、このディレクトリ・オブジェクトに対応付けられているすべてのファイルのすべてのセッションからの操作が正常に実行されなくなります。さらに、これらのファイルを正常にクローズする前にDROPコマンドまたはREPLACEコマンドを実行した場合は、プログラムにおけるこれらのファイルへの参照が失われ、これらのファイルに対応付けられているシステム・リソースも、セッションを停止するまで解放されなくなります。

    この場合、PL/SQLユーザーに可能な手段は、たとえばDBMS_LOB.FILECLOSEALLをコールするプログラム・ブロックを実行してファイル操作を再開するか、または各セッションをすべて終了するかのいずれかです。したがって、これらのコマンドは慎重に使用し、できればメンテナンスの停止時間中に使用します。

  • ユーザーのDIRECTORYオブジェクト権限を取り消すときには、十分な注意が必要です。REVOKE文を使用してユーザーのDIRECTORYオブジェクト権限を取り消した場合、ユーザーのセッションに依存するファイルへの、その後の操作が正常に実行されません。ユーザーは、権限を再取得してファイルをクローズするか、またはセッションでFILECLOSEALLを実行し、ファイル操作を再開する必要があります。

一般的に、ファイル・アクセスの管理にディレクトリ・オブジェクトを使用することは、OSレベルでのシステム管理作業の延長です。ファイルは、計画を立てることによって、Oracleプロセス用のREAD権限を持つ適切なディレクトリに論理的に構成できます。

これらの物理ファイルにマップするREAD権限とともにディレクトリ・オブジェクトを作成し、特定のデータベース・ユーザーにこれらのディレクトリへのアクセス権限を付与できます。

11.6.7 共有サーバー(マルチスレッド・サーバー)・モードのBFILE

データベースでは、共有サーバー(マルチスレッド・サーバー)・モードでのBFILEデータ型のセッション移行がサポートされません。これは、オープンされたBFILEインスタンスに対する操作を、共有サーバーへのコール終了後も継続できることを意味します。

BFILE操作が含まれる共有サーバーのセッションは、1台の共有サーバーに限定され、サーバー間での移行はできません。

11.6.8 外部LOB(BFILE)ロケータ

BFILEでは、値はサーバー側のオペレーティング・システム・ファイル(データベースの外部)に格納されます。そのファイルを参照するBFILEロケータは、インラインに格納されます。

11.6.8.1 BFILE表内の2つの行が同じファイルを参照するとき

DBMS_LOB.FILEOPENで使用されるBFILEロケータ変数(たとえば、L1)が、別のロケータ変数(たとえば、L2)に割り当てられる場合、L1とL2の両方が同じファイルを示します。

つまり、BFILE列がある1つの表の2つの行が、同じファイルまたは別の2つのファイルを参照できるということです。この点は、賢明な開発者にとってはメリットになりますが、不注意な開発者にとっては落とし穴にもなりかねません。

11.6.8.2 BFILEロケータ変数

BFILEロケータ変数は、他の自動変数と同じように機能します。ファイル操作の場合の動作は、ほとんどの従来型プログラム言語の標準入出力ライブラリの一部として使用可能なファイル・ディスクリプタと同様です。

BFILEロケータを定義および初期化し、このロケータによって参照されるファイルをオープンした場合、このファイルをクローズするまでのすべての操作は、このロケータまたはこのロケータのローカル・コピーを使用して、同じプログラム・ブロック内から実行する必要があることを意味します。

11.6.8.3 BFILE固有のガイドライン

BFILEを操作するときのガイドラインは、次のとおりです。

  • ファイルは、同じネスト・レベルにある、同じプログラム・ブロックからオープンおよびクローズします。BFILEロケータ変数は、スカラーと同様、他のプロシージャ、メンバー・メソッドまたは外部関数コールアウトのパラメータとして使用できます。ただし、ファイルのオープンおよびクローズは、同じネスト・レベルにある、同じプログラム・ブロックから行うことをお薦めします。

  • オブジェクトをデータベースにフラッシュする前にBFILE値を設定します。オブジェクトにBFILEが含まれる場合は、オブジェクトをデータベースにフラッシュする前にBFILE値を設定し、新しい行を挿入する必要があります。つまり、OCIObjectNew()とOCIObjectFlush()の間にOCILobFileSetName()をコールする必要があります。

  • BFILEを挿入または更新する前に、ディレクトリ・オブジェクト名およびファイル名を指定します。ディレクトリ・オブジェクト名とファイル名を指定せずにBFILEを挿入または更新すると、エラーになります。

    この規則は、INSERT文またはUPDATE文でBFILEに対してOCIバインド変数を使用するユーザーにも適用されます。OCIバインド変数は、挿入または更新の文を発行する前に、ディレクトリ・オブジェクト名とファイル名で初期化する必要があります。

  • 挿入または更新する前にBFILEを初期化します。

    ノート:

    OCISetAttr()では、BFILEロケータをNULLに設定できません。

  • BFILEを持つ行を挿入または更新するためのSQLを使用する前に、BFILEを次のいずれかに初期化する必要があります。

    • NULL(OCIバインド変数を使用している場合は不可)

    • ディレクトリ・オブジェクト名とファイル名

  • パス名の指定のどこにも2つのピリオド(「..」)を含めることはできません。ファイル名の最初に2つのピリオドを使用することもできません。

11.7 BFILEデータを使用したLOBのロードについて

LOBにBFILEのデータをロードできます。

関連項目:

BFILE操作と各プログラム環境で提供されるAPIのリストは、表11-1を参照してください。

この章で説明するBFILE機能の使用方法の詳細は、『Oracle Database JDBC開発者ガイド』を参照してください。

事前条件

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

  • ソースBFILEインスタンスが存在すること。

  • 宛先のLOBインスタンスが存在すること。

使用上のノート

ノート:

LOADBLOBFROMFILEおよびLOADCLOBFROMFILEプロシージャによって、このプロシージャの機能が実装されるため、バイナリ・データおよび文字データのロード機能が向上します。機能が向上したプロシージャは、PL/SQL環境でのみ使用できます。可能なかぎり、機能が向上したプロシージャを使用することをお薦めします。

関連項目:

文字セットの変換

OCI、またはOCI機能にアクセスする任意のプログラム環境を使用すると、文字セット間を翻訳するとき、文字セット変換が暗黙的に実行されます。

BFILEからCLOBまたはNCLOBへのロード: バイナリ・データから文字セットへの変換

DBMS_LOB.LOADFROMFILEプロシージャを使用してCLOBまたはNCLOBに移入する場合は、BFILEのバイナリ・データをLOBに移入することになります。バイナリ・データから文字セットへは、暗黙的な翻訳は実行されません。このため、テキストをロードする場合はLOADCLOBFROMFILEプロシージャを使用する必要があります。

関連項目:

量パラメータ

量パラメータには、次の注意事項があります。

  • DBMS_LOB.LOADFROMFILE

    BFILE全体をロードする場合は、DBMS_LOB.LOBMAXSIZE定数を渡すことができます。他の値を渡す場合、値はBFILEのサイズ以下である必要があります。

  • OCILobLoadFromFile()

    BFILE全体をロードする場合は、UB4MAXVAL定数を渡すことができます。他の値を渡す場合、値はBFILEのサイズ以下である必要があります。

  • OCILobLoadFromFile2()

    BFILE全体をロードする場合は、UB8MAXVAL定数を渡すことができます。他の値を渡す場合、値はBFILEのサイズ以下である必要があります。

    関連項目:

    量パラメータの最大値の詳細は、表12-2を参照してください。

構文

各プログラム環境における構文については、次のマニュアルの項を参照してください。

例

次のプログラム環境での例を示します。

  • PL/SQL(DBMS_LOB): floaddat.sql

  • OCI: floaddat.c

  • Java(JDBC): 例は提供されません。

11.8 OPENを使用したBFILEのオープンについて

OPENファンクションを使用してBFILEをオープンできます。

ノート:

BFILEをオープンするには、FILEOPENファンクションを使用する方法もありますが、新規に開発する場合にはOPENファンクションを使用することをお薦めします。

関連項目:

構文

各プログラム環境における構文については、次のマニュアルの項を参照してください。

使用例

次の例では、オペレーティング・システム・ファイルADPHOTO_DIRのイメージをオープンします。

例

次のプログラム環境での例を示します。

  • PL/SQL (DBMS_LOB): fopen.sql

  • OCI: fopen.c

  • Java (JDBC): fopen.java

11.9 FILEOPENを使用したBFILEのオープンについて

FILEOPENファンクションを使用してBFILEをオープンできます。

ノート:

新規アプリケーション開発には、FILEOPENファンクションをお薦めしません。OPENファンクションを使用することをお薦めします。

関連項目:

BFILEオープン時の使用上のノート

従来のFILEOPENフォームも引き続き使用できますが、今後の拡張が容易になるため、OPENに切り替えることをお薦めします。

構文

各プログラム環境における構文については、次のマニュアルの項を参照してください。

BFILEのオープンの使用例

これらの例では、ディレクトリ・オブジェクトMEDIA_DIRでkeyboard_logo.jpgを開きます。

例

次のプログラム環境での例を示します。

  • PL/SQL(DBMS_LOB): ffilopen.sql

  • OCI: ffilopen.c

  • Java (JDBC): ffilopen.java

11.10 ISOPENを使用した、BFILEがオープンしているかどうかの確認について

ISOPENを使用して、BFILEがオープンしているかどうかを確認できます。

ノート:

新規アプリケーション開発には、このファンクション(ISOPEN)をお薦めします。新規開発には、古いFILEISOPENファンクションをお薦めしません。

関連項目:

構文

各プログラム環境における構文については、次のマニュアルの項を参照してください。

例

次のプログラム環境での例を示します。

  • PL/SQL(DBMS_LOB): fisopen.sql

  • OCI: fisopen.c

  • Java (JDBC): fisopen.java

11.11 FILEISOPENを使用した、BFILEがオープンしているかどうかの確認について

FILEISOPENファンクションを使用して、BFILEがOPENであるかどうかを確認できます。

ノート:

新規アプリケーション開発には、FILEISOPENファンクションをお薦めしません。ISOPENファンクションを使用することをお薦めします。

関連項目:

使用上のノート

従来のFILEISOPENフォームも引き続き使用できますが、今後の拡張が容易になるため、ISOPENに切り替えることをお薦めします。

構文

各プログラム環境における構文については、次のマニュアルの項を参照してください。

  • PL/SQL (DBMS_LOB): 『Oracle Database PL/SQLパッケージ・プロシージャおよびタイプ・リファレンス』の「DBMS_LOB」のFILEISOPENに関する項

  • C (OCI): 『Oracle Call Interfaceプログラマーズ・ガイド』の第7章「LOBとBFILEの操作」の使用上のノートに関する項。第16章、LOB関数のOCILobFileIsOpen()に関する項。

  • COBOL(Pro*COBOL): 参照マニュアルはありません。

  • C/C++(Pro*C/C++): 参照マニュアルはありません。

  • Java (JDBC): 『Oracle Database JDBC開発者ガイド』の「LOBとBFILEの操作」のBFILEの操作に関する項。

シナリオ

次の例では、ad_graphicに対応付けられているBFILEがオープンしているかどうかを問い合せます。

例

次のプログラム環境での例を示します。

  • PL/SQL (DBMS_LOB): ffisopen.sql

  • OCI: ffisopen.c

  • Java (JDBC): ffisopen.java

11.12 BFILEデータの表示について

BFILEデータは、プログラム環境によって異なる様々な操作を使用して表示できます。

関連項目:

BFILE操作と各プログラム環境で提供されるAPIのリストは、表11-1を参照してください。

構文

各プログラム環境における構文については、次のマニュアルの項を参照してください。

例

次のプログラム環境での例を示します。

  • PL/SQL(DBMS_LOB): fdisplay.sql

  • OCI: fdisplay.c

  • Java (JDBC): fdisplay.java

11.13 BFILEからのデータの読取りについて

BFILEからデータを読み取ることができます。

関連項目:

BFILE操作と各プログラム環境で提供されるAPIのリストは、表11-1を参照してください。

使用上のノート

この操作を使用する場合は、次のことに注意してください。

OCIでのストリーム読取り

大量のBFILEデータを最も効率よく読み取るには、ストリーム・メカニズムを有効にしたOCILobRead2()でポーリングまたはコールバックを使用します。そのためには、次のようにoffsetパラメータを使用して読取り開始位置を指定します。 

ub8  char_amt =  0;
ub8  byte_amt =  0;
ub4  offset = 1000;

OCILobRead2(svchp, errhp, locp, &byte_amt, &char_amt, offset, bufp, bufl,
            OCI_ONE_PIECE, 0, 0, 0, 0);

ポーリング・モードを使用した場合は、各OCILobRead2()コール後にbyte_amtパラメータの値を調べて、バッファに何バイト読み取られたかを確認してください。これは、バッファがいっぱいになっていない場合があるためです。

コールバックを使用する場合、lenpパラメータはコールバックへの入力で、バッファ内で格納されたバイト数を示します。バッファの空き領域を確認するため、コールバック処理中にlenpパラメータを必ずチェックしてください。

量パラメータ

  • DBMS_LOB.READをコールするとき、量パラメータをデータのサイズより大きくすることはできますが、量パラメータはバッファのサイズ以下にする必要があります。PL/SQLで、バッファサイズの上限は32Kです。

  • BFILEの終わりまで読み取る場合は、OCILobRead2()のコール時にbyte_amtパラメータに値0 (ゼロ)を渡すことができます。

関連項目:

Oracle Call Interfaceプログラマーズ・ガイド

構文

各プログラム環境における構文については、次のマニュアルの項を参照してください。

例

次のプログラム環境での例を示します。

  • PL/SQL(DBMS_LOB): fread.sql

  • OCI: fread.c

  • Java (JDBC): fread.java

11.14 SUBSTRを使用した、BFILEデータの一部の読取りについて

SUBSTRを使用してBFILEデータの一部を読み取ることができます。

関連項目:

BFILE操作と各プログラム環境で提供されるAPIのリストは、表11-1を参照してください。

構文

各プログラム環境における構文については、次のマニュアルの項を参照してください。

例

次のプログラム環境での例を示します。

  • PL/SQL(DBMS_LOB): freadprt.sql

  • C(OCI): 今回のリリースでは例は提供されません。

  • Java (JDBC): freadprt.java

11.15 2つのBFILEの全体または一部の比較

2つのBFILEの全体または一部を比較できます。

関連項目:

BFILE操作と各プログラム環境で提供されるAPIのリストは、表11-1を参照してください。

構文

各プログラム環境における構文については、次のマニュアルの項を参照してください。

例

次のプログラム環境での例を示します。

  • PL/SQL (DBMS_LOB): fcompare.sql

  • OCI: 今回のリリースでは例は提供されません。

  • Java (JDBC): fcompare.java

11.16 INSTRを使用した、BFILEにパターンが存在するかどうかの確認

INSTR操作を使用して、BFILEにパターンが存在するかどうかを確認できます。

関連項目:

BFILE操作と各プログラム環境で提供されるAPIのリストは、表11-1を参照してください。

構文

各プログラム環境における構文については、次のマニュアルの項を参照してください。

例

次のプログラム環境での例を示します。

  • PL/SQL(DBMS_LOB): fpattern.sql

  • OCI: 今回のリリースでは例は提供されません。

  • Java (JDBC): fpattern.java

11.17 BFILEが存在するかどうかの確認

このプロシージャでは、BFILEロケータが有効なBFILEインスタンスを指しているかどうかを確認します。

関連項目:

BFILE操作と各プログラム環境で提供されるAPIのリストは、表11-1を参照してください。

構文

各プログラム環境における構文については、次のマニュアルの項を参照してください。

例

次のプログラム環境での例を示します。

  • PL/SQL(DBMS_LOB): fexists.sql

  • OCI: fexists.c

  • Java (JDBC): fexists.java

11.18 BFILEの長さの取得

BFILEの長さを取得できます。

関連項目:

BFILE操作と各プログラム環境で提供されるAPIのリストは、表11-1を参照してください。

構文

各プログラム環境における構文については、次のマニュアルの項を参照してください。

例

次のプログラム環境での例を示します。

  • PL/SQL(DBMS_LOB): flength.sql

  • OCI: flength.c

  • Java (JDBC): flength.java

11.19 BFILEロケータの割当てについて

1つのBFILEロケータを別のロケータに割り当てることができます。

関連項目:

BFILE操作と各プログラム環境で提供されるAPIのリストは、表11-1を参照してください。

構文

各プログラム環境における構文については、次のマニュアルの項を参照してください。

  • SQL: 『Oracle Database SQL言語リファレンス』の第7章「SQL文」のCREATE PROCEDUREに関する項

  • PL/SQL (DBMS_LOB): LOBロケータを他のLOBロケータに割り当てる方法は、「高度な設計時の考慮事項」を参照してください。

  • C (OCI): 『Oracle Call Interfaceプログラマーズ・ガイド』の第7章「LOBとBFILEの操作」の使用上のノートに関する項。第16章、LOB関数のOCILobLocatorAssign()に関する項。

  • COBOL (Pro*COBOL): 『Pro*COBOLプログラマーズ・ガイド』のLOBの詳細、LOB文の使用上のノート、およびLOB ASSIGN実行可能埋込みSQL拡張。

  • C/C++(Pro*C/C++): 『Pro*C/C++プログラマーズ・ガイド』の「ラージ・オブジェクト(LOB)」、「LOB文」および「埋込みSQL文およびディレクティブ」の「LOB ASSIGN」

  • Java (JDBC): 『Oracle Database JDBC開発者ガイド』の「LOBとBFILEの操作」のBFILEの操作に関する項。

例

次のプログラム環境での例を示します。

  • PL/SQL(DBMS_LOB): fcopyloc.sql

  • OCI: fcopyloc.c

  • Java (JDBC): fcopyloc.java

11.20 BFILEのディレクトリ・オブジェクト名とファイル名の取得

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

関連項目:

BFILE操作と各プログラム環境で提供されるAPIのリストは、表11-1を参照してください。

構文

各プログラム環境における構文については、次のマニュアルの項を参照してください。

例

次のプログラム環境での、このプロシージャの例を示します。

  • PL/SQL(DBMS_LOB): fgetdir.sql

  • OCI: fgetdir.c

  • Java (JDBC): fgetdir.java

11.21 初期化したBFILEロケータを使用したBFILEの更新について

BFILEロケータを初期化してBFILEを更新できます。

関連項目:

BFILE操作と各プログラム環境で提供されるAPIのリストは、表11-1を参照してください。

構文

各プログラム環境における構文については、次のマニュアルの項を参照してください。

例

  • PL/SQL(DBMS_LOB): fupdate.sql

  • OCI: fupdate.c

  • Java (JDBC): fupdate.java

11.22 FILECLOSEを使用したBFILEのクローズ

FILECLOSEを使用してBFILEをクローズできます。

ノート:

新規開発には、このファンクション(FILECLOSE)をお薦めしません。かわりにCLOSEファンクションを使用してください。

関連項目:

CLOSEを使用したBFILEのクローズ

BFILE操作と各プログラム環境で提供されるAPIのリストは、表11-1を参照してください。

構文

各プログラム環境における構文については、次のマニュアルの項を参照してください。

  • PL/SQL(DBMS_LOB): 『Oracle Database PL/SQLパッケージ・プロシージャおよびタイプ・リファレンス』の「DBMS_LOB」の「FILEOPEN」および「FILECLOSE」

  • C (OCI): 『Oracle Call Interfaceプログラマーズ・ガイド』の第7章「LOBとBFILEの操作」の使用上のノートに関する項。第16章、LOB関数のOCILobFileClose()に関する項。

  • COBOL(Pro*COBOL): 参照マニュアルはありません。

  • C/C++(Pro*C/C++): 参照マニュアルはありません。

  • Java (JDBC): 『Oracle Database JDBC開発者ガイド』の「LOBとBFILEの操作」のBFILEの操作に関する項。

例

  • PL/SQL(DBMS_LOB): fclose_f.sql

  • OCI: fclose_f.c

  • Java(JDBC): fclose_f.java

11.23 CLOSEを使用したBFILEのクローズ

CLOSEファンクションを使用してBFILEをクローズできます。

ノート:

新規アプリケーション開発には、このファンクション(CLOSE)をお薦めします。新規開発には、古いFILECLOSEファンクションをお薦めしません。

関連項目:

BFILE操作と各プログラム環境で提供されるAPIのリストは、表11-1を参照してください。

使用上のノート

BFILEのオープンとクローズは必須操作です。インスタンスはセッション中に後でクローズする必要があります。

関連項目:

構文

各プログラム環境における構文については、次のマニュアルの項を参照してください。

例

  • PL/SQL(DBMS_LOB): fclose_c.sql

  • OCI: fclose_c.c

  • Java(JDBC): fclose_c.java

11.24 FILECLOSEALLを使用したオープン中のすべてのBFILEのクローズ

オープンしているBFILEをすべてクローズできます。

BFILEインスタンスは、プログラムの終了前にクローズする必要があります。たとえば、オープンしているBFILEインスタンスはすべて、PL/SQLブロックやOCIプログラムの終了する前にクローズする必要があります。

アプリケーションに例外が発生したり異常終了した場合も、オープンしているBFILEインスタンスをクローズする必要があります。このような場合にBFILEインスタンスをクローズしないと、データベースでオープン状態であるとみなされます。このような場合にBFILEインスタンスがオープン状態のままにならないような例外処理方法を使用していることを確認してください。

関連項目:

構文

各プログラム環境における構文については、次のマニュアルの項を参照してください。

  • PL/SQL (DBMS_LOB): 『Oracle Database PL/SQLパッケージ・プロシージャおよびタイプ・リファレンス』の「DBMS_LOB」のFILECLOSEALLに関する項

  • C (OCI): 『Oracle Call Interfaceプログラマーズ・ガイド』の第7章「LOBとBFILEの操作」の使用上のノートに関する項。第16章、LOB関数のOCILobFileCloseAll()に関する項。

  • COBOL (Pro*COBOL): 『Pro*COBOLプログラマーズ・ガイド』のLOBの詳細、LOB文の使用上のノート、およびLOB FILE CLOSE ALL実行可能埋込みSQL拡張

  • C/C++(Pro*C/C++): 『Pro*C/C++プログラマーズ・ガイド』の「ラージ・オブジェクト(LOB)」、「LOB文」および「埋込みSQL文およびディレクティブ」のLOB FILE CLOSE ALLに関する説明

  • Java (JDBC): 『Oracle Database JDBC開発者ガイド』の第7章「LOBとBFILEの操作」のBFILEの操作に関する項。

例

  • PL/SQL(DBMS_LOB): fclosea.sql

  • OCI: fclosea.c

  • Java (JDBC): fclosea.java

11.25 BFILEを含む行の挿入について

BFILEロケータを初期化してBFILEを含む行を挿入できます。

関連項目:

  • BFILE操作と各プログラム環境で提供されるAPIのリストは、表11-1を参照してください。

使用上のノート

INSERT文を発行する前に、BFILEロケータ・バインド変数をNULLまたはディレクトリ・オブジェクトおよびファイル名に初期化する必要があります。

構文

各プログラム環境における構文については、次のマニュアルの項を参照してください。

例

  • PL/SQL(DBMS_LOB): finsert.sql

  • OCI: finsert.c

  • Java (JDBC): finsert.java