日本語PDF
  1. PL/SQLパッケージおよびタイプ・リファレンス
  2. DBMS_FILE_TRANSFER

72 DBMS_FILE_TRANSFER

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

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

参照:

ファイル転送の使用方法については、『Oracle Database管理者ガイド』を参照してください。

72.1 DBMS_FILE_TRANSFERの概要

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

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

72.2 DBMS_FILE_TRANSFERのセキュリティ・モデル

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

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

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

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

72.3 DBMS_FILE_TRANSFERの操作上のノート

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

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

72.4 DBMS_FILE_TRANSFERサブプログラムの要約

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

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

サブプログラム 説明

COPY_FILEプロシージャ

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

GET_FILEプロシージャ

リモート・データベースに接続し、リモート・ファイルを読み取り、ローカル・ファイル・システムまたはASMにそのファイルのコピーを作成します。

PUT_FILEプロシージャ

ローカル・ファイルまたはASMを読み取り、リモート・データベースに接続して、リモート・ファイル・システムにそのファイルのコピーを作成します。

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

パラメータ

表72-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以下である必要があります。

このプロシージャを実行する前に、source_directory_objectパラメータによって指定されたディレクトリ内のファイルをsource_file_name パラメータに指定し、destination_directory_objectパラメータに指定された新しい場所のファイルの新しい名前をdestination_file_nameパラメータに指定する必要があります。source_directory_objectおよびdestination_directory_objectパラメータのディレクトリ・オブジェクトには、相対パスおよびシンボリック・リンクは許可されません。

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

参照:

ファイル転送の使用方法については、『Oracle Automatic Storage Management管理者ガイド』を参照してください。

例

SQL> create directory DGROUP as '+diskgroup1/dbs/backup';
 
Directory created.
 
SQL>  BEGIN
   2    DBMS_FILE_TRANSFER.COPY_FILE('SOURCEDIR','t_xdbtmp.f', 'DGROUP', 
                                   't_xdbtmp.f');
   3  END;
   4  /
 
PL/SQL procedure successfully completed.
 
SQL> EXIT
$ASMCMD
ASMCMD> ls
DISKGROUP1/
ASMCMD> cd diskgroup1/dbs/backup
ASMCMD> ls
t_xdbtmp.f => +DISKGROUP1/ORCL/TEMPFILE/COPY_FILE.267.546546525

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

パラメータ

表72-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 ;
/

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

パラメータ

表72-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以下である必要があります。

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

例

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 ;