69 DBMS_FILE_TRANSFER

DBMS_FILE_TRANSFERパッケージは、データベース内のバイナリ・ファイルをコピーし、データベース間でバイナリ・ファイルを転送するプロシージャを提供します。

DBMS_FILE_TRANSFERの使用方法

概要
セキュリティ・モデル
使用上の注意

概要

DBMS_FILE_TRANSFERパッケージは、データベース内のバイナリ・ファイルをコピーし、データベース間でバイナリ・ファイルを転送するプロシージャを提供します。エンディアンの異なるプラットフォームからファイルを受け取ると、宛先データベースにより各ブロックが変換されます。データファイルは、トランスポータブル操作(RMAN変換なし)の一環として接続先データベースに移動された後でインポートできます。GETおよびPUT操作は両方とも、プラットフォーム間の相違を反映するように宛先のファイル内で変換されます。一方、COPYはローカル操作であるため、変換は不要です。

セキュリティ・モデル

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

このインタフェースを使用するには、次のユーザーに次の権限が必要です。

ローカル・データベースの現在のユーザーには、source_directory_objectパラメータに指定したディレクトリ・オブジェクトに対するREAD権限が必要です。
宛先データベースの接続ユーザーには、destination_directory_objectパラメータに指定したディレクトリ・オブジェクトについてのWRITE権限が必要です。

使用上の注意

注意:

DBMS_FILE_TRANSFERでは、オンライン・バックアップがサポートされています。データベースで変更中のファイルをコピーまたは転送する場合は、ファイルの一貫性が失われリカバリが必要になる可能性があるため、注意する必要があります。一貫性を保証するには、データベースの使用中はファイルをオフラインにしてください。

バックアップの実行にDBMS_FILE_TRANSFERを使用する場合は、自己管理バックアップを実行するため、ファイルをホット・バックアップ・モードにする必要があります。

DBMS_FILE_TRANSFERサブプログラムの要約

表69-1 DBMS_FILE_TRANSFERパッケージのサブプログラム

サブプログラム	説明
COPY_FILEプロシージャ	ソース・ディレクトリからファイルを読み取り、宛先ディレクトリにそのコピーを作成します。ソース・ディレクトリと宛先ディレクトリは、両方ともローカル・ファイル・システム内または自動ストレージ管理(ASM)ディスク・グループ内に指定するか、ローカル・ファイル・システムとASMの間に指定して、いずれの方向にもコピーを実行できます。
GET_FILEプロシージャ	リモート・データベースに接続し、リモート・ファイルを読み取り、ローカル・ファイル・システムまたはASMにそのファイルのコピーを作成します。
PUT_FILEプロシージャ	ローカル・ファイルまたはASMを読み取り、リモート・データベースに接続して、リモート・ファイル・システムにそのファイルのコピーを作成します。

COPY_FILEプロシージャ

このプロシージャは、ソース・ディレクトリからファイルを読み取り、宛先ディレクトリにそのコピーを作成します。ソース・ディレクトリと宛先ディレクトリは、両方ともローカル・ファイル・システム内または自動ストレージ管理(ASM)ディスク・グループ内に指定するか、ローカル・ファイル・システムとASMの間に指定して、いずれの方向にもコピーを実行できます。

ローカル・ファイル・システムは、すべてのタイプのファイルのコピー元およびコピー先に指定できます。ただし、ASMディスク・グループは、データベース・ファイル(データファイル、一時ファイル、制御ファイルなど)のみのコピー元およびコピー先となります。

宛先ファイルはプロシージャが正常に終了するまで閉じられません。

構文

DBMS_FILE_TRANSFER.COPY_FILE(
   source_directory_object       IN  VARCHAR2,
   source_file_name              IN  VARCHAR2,
   destination_directory_object  IN  VARCHAR2,
   destination_file_name         IN  VARCHAR2);

パラメータ

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

パラメータ	説明
`source_directory_object`	ソース・ディレクトリを指定するディレクトリ・オブジェクト。このディレクトリ・オブジェクトは、すでに存在している必要があります。(ディレクトリ・オブジェクトは、`CREATE` `DIRECTORY`コマンドを使用して作成します)。
`source_file_name`	コピーするファイルの名前。このファイルは、ソース・ディレクトリ内に存在している必要があります。
`destination_directory_object`	宛先ディレクトリを指定するディレクトリ・オブジェクト。このディレクトリ・オブジェクトは、すでに存在している必要があります。宛先がASMの場合、このディレクトリ・オブジェクトは、ディスク・グループ名(+`diskgroup1`など)または別名で作成されたディレクトリを指定する必要があります。ディレクトリを指定する場合は、ディレクトリのフルパス(`+diskgroup1/dbs/control`など)を指定します。
`destination_file_name`	宛先ディレクトリ内のファイルに割り当てる名前。同じ名前のファイルが宛先ディレクトリに存在しないようにしてください。宛先がASMの場合は、次のようになります。ファイルは、データベース名およびファイル・タイプに応じて、完全修飾ASMファイル名を割り当てられ、適切なディレクトリ内に作成されます。ファイルに割り当てられるファイル・タイプのタグは、`COPY_FILE`です。 `destination_file_name`引数の値は、指定した宛先ディレクトリ内でファイルの別名になります。ファイル名の後に、カッコで囲んだASMテンプレート名を追加できます。この場合、ファイルには、テンプレートによって指定された属性が付与されます。

使用上の注意

このプロシージャを正常に実行するには、現在のユーザーに次の権限が必要です。

source_directory_objectパラメータに指定したディレクトリ・オブジェクトについてのREAD権限
destination_directory_objectパラメータに指定したディレクトリ・オブジェクトについてのWRITE権限

このプロシージャは二重引用符で囲まれていないディレクトリ・オブジェクト・パラメータを大文字に変換しますが、ファイル名は大文字に変換しません。

さらに、コピーされるファイルは次の要件を満たしている必要があります。

コピーされるファイルのサイズは512バイトの倍数である必要があります。
コピーされるファイルのサイズは、2TB以下である必要があります。

ファイルの転送はトランザクション処理ではありません。長いファイルのコピーの進行状況を監視するには、V$SESSION_LONGOPS動的パフォーマンス・ビューに問い合せてください。

GET_FILEプロシージャ

このプロシージャは、リモート・データベースに接続し、リモート・ファイルを読み取り、ローカル・ファイル・システムまたはASMにそのファイルのコピーを作成します。コピーされるファイルはソース・ファイルで、コピーで作成された新しいファイルが宛先ファイルです。宛先ファイルはプロシージャが正常に終了するまで閉じられません。

構文

DBMS_FILE_TRANSFER.GET_FILE
   source_directory_object      IN  VARCHAR2,    
   source_file_name             IN  VARCHAR2,  
   source_database              IN  VARCHAR2,  
   destination_directory_object IN  VARCHAR2,
   destination_file_name        IN  VARCHAR2);

パラメータ

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

パラメータ	説明
`source_directory_object`	ソース・サイトにある、ファイルのコピー元のディレクトリ・オブジェクト。このディレクトリ・オブジェクトはソース・サイトに存在している必要があります。
`source_file_name`	リモート・ファイル・システムにおいてコピーされるファイルの名前。このファイルは、リモート・ファイル・システムのソース・ディレクトリ・オブジェクトに関連付けられたディレクトリに存在している必要があります。
`source_database`	ファイルが存在するリモート・データベースへのデータベース・リンクの名前。
`destination_directory_object`	宛先サイトにある、ファイルのコピー先となるディレクトリ・オブジェクト。このディレクトリ・オブジェクトはローカル・ファイル・システムに存在している必要があります。
`destination_file_name`	ローカル・ファイル・システムにコピーされるファイルの名前。同じ名前のファイルがローカル・ファイル・システムの宛先ディレクトリに存在しないようにしてください。

使用上の注意

このプロシージャを正常に実行するには、次のユーザーに次の権限が必要です。

ソース・データベースの接続されるユーザーには、source_directory_objectパラメータに指定したディレクトリ・オブジェクトについての読取り権限が必要です。
ローカル・データベースの現在のユーザーには、destination_directory_objectパラメータに指定したディレクトリ・オブジェクトについての書込み権限が必要です。

さらに、コピーされるファイルは次の要件を満たしている必要があります。

コピーされるファイルのサイズは512バイトの倍数である必要があります。
コピーされるファイルのサイズは、2TB以下である必要があります。

ファイルの転送はトランザクション処理ではありません。長いファイルの転送の進行状況を監視するには、V$SESSION_LONGOPS動的パフォーマンス・ビューに問い合せてください。

例

CREATE OR REPLACE DIRECTORY df AS '+datafile' ;
GRANT WRITE ON DIRECTORY df TO "user";
CREATE DIRECTORY DSK_FILES AS ''^t_work^'';
GRANT WRITE ON DIRECTORY dsk_files TO "user";
 
-- asumes that dbs2 link has been created and we are connected to the instance. 
-- dbs2 could be a loopback or point to another instance.
 
BEGIN
-- asm file to an os file
-- get an asm file from dbs1.asm/a1 to dbs2.^t_work^/oa5.dat
  DBMS_FILE_TRANSFER.GET_FILE ( 'df' , 'a1' , 'dbs1', 'dsk_files' , 'oa5.dat' );
 
-- os file to an os file
-- get an os file from dbs1.^t_work^/a2.dat to dbs2.^t_work^/a2back.dat
  DBMS_FILE_TRANSFER.GET_FILE ( 'dsk_files' , 'a2.dat' , 'dbs1', 'dsk_files' , 'a2back.dat' );
 
END ;
/

PUT_FILEプロシージャ

このプロシージャは、ローカル・ファイルまたはASMを読み取り、リモート・データベースに接続して、リモート・ファイル・システムにそのファイルのコピーを作成します。コピーされるファイルはソース・ファイルで、コピーで作成された新しいファイルが宛先ファイルです。宛先ファイルはプロシージャが正常に終了するまで閉じられません。

構文

DBMS_FILE_TRANSFER.PUT_FILE(
   source_directory_object       IN  VARCHAR2,   
   source_file_name              IN  VARCHAR2,
   destination_directory_object  IN  VARCHAR2,
   destination_file_name         IN  VARCHAR2,  
   destination_database          IN  VARCHAR2);

パラメータ

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

パラメータ	説明
`source_directory_object`	ローカル・ソース・サイトにある、ファイルのコピー元のディレクトリ・オブジェクト。このディレクトリ・オブジェクトはソース・サイトに存在している必要があります。
`source_file_name`	ローカル・ファイル・システムからコピーされるファイルの名前。このファイルは、ローカル・ファイル・システムのソース・ディレクトリ・オブジェクトに関連付けられたディレクトリに存在している必要があります。
`destination_directory_object`	宛先サイトにある、ファイルのコピー先となるディレクトリ・オブジェクト。このディレクトリ・オブジェクトはリモート・ファイル・システムに存在している必要があります。
`destination_file_name`	リモート・ファイル・システムにおいてコピーされるファイルの名前。同じ名前のファイルがリモート・ファイル・システムの宛先ディレクトリに存在しないようにしてください。
`destination_database`	ファイルのコピー先となるリモート・データベースへのデータベース・リンクの名前。

使用上の注意

このプロシージャを正常に実行するには、次のユーザーに次の権限が必要です。

ローカル・データベースの現在のユーザーには、source_directory_objectパラメータに指定したディレクトリ・オブジェクトについての読取り権限が必要です。
宛先データベースの接続ユーザーには、destination_directory_objectパラメータに指定したディレクトリ・オブジェクトについての書込み権限が必要です。

さらに、コピーされるファイルは次の要件を満たしている必要があります。

コピーされるファイルのサイズは512バイトの倍数である必要があります。
コピーされるファイルのサイズは、2TB以下である必要があります。

例

CREATE OR REPLACE DIRECTORY df AS '+datafile' ;
GRANT WRITE ON DIRECTORY df TO "user";
CREATE OR REPLACE DIRECTORY ft1 AS '+datafile/ft1' ;
GRANT READ,WRITE ON DIRECTORY ft1 TO "user";
CREATE OR REPLACE DIRECTORY ft1_1 AS '+datafile/ft1/ft1_1' ;
 
CONNECT user;
Enter password: password
 
-- - put a1.dat to a4.dat (using dbs2 dblink)
-- - level 2 sub dir to parent dir
-- - user has read privs on ft1_1 at dbs1 and write on df in dbs2
BEGIN
 DBMS_FILE_TRANSFER.PUT_FILE ( 'ft1_1' , 'a2.dat' , 'df' , 'a4.dat' ,
                               'dbs2' ) ;
END ;