10g リリース2（10.2）
B19211-01
 目次 |
 索引 |
| Oracle Database ユーティリティ 10g リリース2（10.2） B19211-01 |
|
Data Pump API（DBMS_DATAPUMP）は、あるサイトのデータおよびメタデータのすべてまたは一部をデータベース間で移動するための高速メカニズムを提供します。Data Pump ExportおよびData Pump ImportユーティリティはData Pump APIに基づいています。
この章では、Data Pump APIの機能を詳細に説明します。この章の内容は、次のとおりです。
参照:
DBMS_DATAPUMPパッケージで使用可能なプロシージャの詳細は、『Oracle Database PL/SQLパッケージ・プロシージャおよびタイプ・リファレンス』を参照してください。
クライアント・インタフェースで使用されている主な構造体はジョブ・ハンドルで、コール元に対しては整数として表示されます。ハンドルは、DBMS_DATAPUMP.OPENファンクションまたはDBMS_DATAPUMP.ATTACHファンクションを使用して作成します。他のセッションをジョブに接続してその進捗状況を監視および制御できます。この機能によって、DBAは帰宅前にジョブを開始して、自宅でその進捗状況を確認できます。ハンドルはセッション固有です。同じジョブによって、セッションごとに異なるハンドルを作成できます。
次に、各フェーズに関連付けられたジョブの状態を示します。
DBMS_DATAPUMP.START_JOBプロシージャの実行時
DBMS_DATAPUMP.STOP_JOBの実行時
DBMS_DATAPUMP.ATTACHが実行されてから、そのジョブを再開するためにDBMS_DATAPUMP.START_JOBが実行されるまでの期間
「アイドル」状態のジョブに対してDBMS_DATAPUMP.START_JOBを実行すると、「実行中」状態に戻ります。
すべてのユーザーがDBMS_DATAPUMP.DETACHを実行して「定義中」状態のジョブとの接続を切断すると、そのジョブはデータベースから完全に削除されます。
ジョブが異常終了した場合またはジョブを実行しているインスタンスが停止した場合、「実行中」または「アイドル」状態のジョブは「未実行」状態になります。ユーザーは、その状態からジョブを再開できます。
マスター制御プロセスは、「定義中」、「アイドル」、「実行中」、「停止処理中」、「停止保留」、「完了処理中」の状態でアクティブです。また、一時的に「停止」および「完了」の状態にもなります。ジョブのマスター表は、「未定義」状態を除いてすべての状態で存在します。ワーカー・プロセスは「実行中」および「停止保留」状態、つまりインポート・ジョブに対する「定義中」状態でのみアクティブです。
ジョブの状態が「実行中」の場合に接続を切断しても、そのジョブは停止しません。ジョブとの接続は明示的または暗黙的に切断できます。DBMS_DATAPUMP.DETACHプロシージャを実行すると明示的に切断されます。セッションが停止した場合、インスタンスが開始された場合またはSTOP_JOBプロシージャがコールされた場合は暗黙的に切断されます。
「未実行」状態は、実行中のジョブのコンテキストの外部にマスター表が存在することを示します。この状態は、ジョブの完了時にマスター表が明示的に保持された場合、（後で再開するために）ジョブが停止された場合またはジョブが異常終了した場合に発生します。また、この状態は、ジョブの開始時に行われるジョブの状態の移行中、およびマスター表を削除する前に行うジョブの終了時に、一時的に発生する場合があります。「未実行」状態は、DBA_DATAPUMP_JOBSビューおよびUSER_DATAPUMP_JOBSビューでのみ表示されます。GET_STATUSプロシージャから返されることはありません。
表5-1に、DBMS_DATAPUMPプロシージャを実行できる有効なジョブの状態を示します。この表に示す状態は、特に指定がないかぎり、エクスポートとインポートの両方で有効です。
Data Pump APIを使用するには、DBMS_DATAPUMPパッケージで提供されるプロシージャを使用します。次の手順では、Data Pump APIの使用に関連する基本操作を示します。通常操作を行う順序でこれらの手順を示します。
DBMS_DATAPUMP.OPENプロシージャを実行して、Data Pumpジョブとのそのインフラストラクチャを作成します。
これらの手順の概要は、次の項で示す使用例で説明します。
この項では、Data Pump APIの使用方法を理解するために有効な例を示します。
これらの例は、PL/SQLスクリプトの形式で記述します。これらのスクリプトをコピーして実行するには、まず、SQL*Plusを使用して次の操作を実行する必要があります。
READおよびWRITE権限を付与します。たとえば、権限を持つdmpdirというディレクトリ・オブジェクトを作成するには、次のように行います。userは、ユーザー名に置き換えます。
SQL> CREATE DIRECTORY dmpdir AS '/rdbms/work'; SQL> GRANT READ, WRITE ON DIRECTORY dmpdir TO user
EXP_FULL_DATABASEロールおよびIMP_FULL_DATABASEロールを所有していることを確認します。セキュリティ・ドメイン内でユーザー自身に割り当てられているすべてのロールのリストを表示するには、次のように行います。
SQL> SELECT * FROM SESSION_ROLES;
必要なロールが割り当てられていない場合は、システム管理者に連絡してください。
SQL> SET SERVEROUTPUT ON
これを行わなかった場合は、画面に出力が表示されません。この操作は、例を実行するセッションと同じセッションで行う必要があります。また、この設定は、SQL*Plusを終了すると失われるため、新しいセッションの開始時に再設定する必要があります。
次の例のPL/SQLスクリプトは、Data Pump APIを使用してHRスキーマのスキーマ・エクスポートを簡単に実行する方法を示しています。ジョブの作成、開始、監視の方法を示しています。この例の詳細は、スクリプト内のコメントを参照してください。例を簡単にしておくために、APIのコールでの例外は検出されません。ただし、本番環境でエラーが発生した場合は、例外ハンドラを定義してGET_STATUSをコールし、エラー情報の詳細を取得することをお薦めします。
CONNECT SYSTEM/password
DECLARE
ind NUMBER; -- Loop index
h1 NUMBER; -- Data Pump job handle
percent_done NUMBER; -- Percentage of job complete
job_state VARCHAR2(30); -- To keep track of job state
le ku$_LogEntry; -- For WIP and error messages
js ku$_JobStatus; -- The job status from get_status
jd ku$_JobDesc; -- The job description from get_status
sts ku$_Status; -- The status object returned by get_status
BEGIN
-- Create a (user-named) Data Pump job to do a schema export.
h1 := DBMS_DATAPUMP.OPEN('EXPORT','SCHEMA',NULL,'EXAMPLE1','LATEST');
-- Specify a single dump file for the job (using the handle just returned)
-- and a directory object, which must already be defined and accessible
-- to the user running this procedure.
DBMS_DATAPUMP.ADD_FILE(h1,'example1.dmp','DMPDIR');
-- A metadata filter is used to specify the schema that will be exported.
DBMS_DATAPUMP.METADATA_FILTER(h1,'SCHEMA_EXPR','IN (''HR'')');
-- Start the job. An exception will be generated if something is not set up
-- properly.
DBMS_DATAPUMP.START_JOB(h1);
-- The export job should now be running. In the following loop, the job
-- is monitored until it completes. In the meantime, progress information is
-- displayed.
percent_done := 0;
job_state := 'UNDEFINED';
while (job_state != 'COMPLETED') and (job_state != 'STOPPED') loop
dbms_datapump.get_status(h1,
dbms_datapump.ku$_status_job_error +
dbms_datapump.ku$_status_job_status +
dbms_datapump.ku$_status_wip,-1,job_state,sts);
js := sts.job_status;
-- If the percentage done changed, display the new value.
if js.percent_done != percent_done
then
dbms_output.put_line('*** Job percent done = ' ||
to_char(js.percent_done));
percent_done := js.percent_done;
end if;
-- If any work-in-progress (WIP) or error messages were received for the job,
-- display them.
if (bitand(sts.mask,dbms_datapump.ku$_status_wip) != 0)
then
le := sts.wip;
else
if (bitand(sts.mask,dbms_datapump.ku$_status_job_error) != 0)
then
le := sts.error;
else
le := null;
end if;
end if;
if le is not null
then
ind := le.FIRST;
while ind is not null loop
dbms_output.put_line(le(ind).LogText);
ind := le.NEXT(ind);
end loop;
end if;
end loop;
-- Indicate that the job finished and detach from it.
dbms_output.put_line('Job has completed');
dbms_output.put_line('Final job state = ' || job_state);
dbms_datapump.detach(h1);
END;
/
この例では、例5-1（hrスキーマのエクスポート）で作成したダンプ・ファイルをインポートします。すべてのスキーマ・オブジェクトがhrスキーマからblakeスキーマに再マップされます。例を簡単にしておくために、APIのコールでの例外は検出されません。ただし、本番環境でエラーが発生した場合は、例外ハンドラを定義してGET_STATUSをコールし、エラー情報の詳細を取得することをお薦めします。
CONNECT SYSTEM/password
DECLARE
ind NUMBER; -- Loop index
h1 NUMBER; -- Data Pump job handle
percent_done NUMBER; -- Percentage of job complete
job_state VARCHAR2(30); -- To keep track of job state
le ku$_LogEntry; -- For WIP and error messages
js ku$_JobStatus; -- The job status from get_status
jd ku$_JobDesc; -- The job description from get_status
sts ku$_Status; -- The status object returned by get_status
BEGIN
-- Create a (user-named) Data Pump job to do a "full" import (everything
-- in the dump file without filtering).
h1 := DBMS_DATAPUMP.OPEN('IMPORT','FULL',NULL,'EXAMPLE2');
-- Specify the single dump file for the job (using the handle just returned)
-- and directory object, which must already be defined and accessible
-- to the user running this procedure. This is the dump file created by
-- the export operation in the first example.
DBMS_DATAPUMP.ADD_FILE(h1,'example1.dmp','DMPDIR');
-- A metadata remap will map all schema objects from HR to BLAKE.
DBMS_DATAPUMP.METADATA_REMAP(h1,'REMAP_SCHEMA','HR','BLAKE');
-- If a table already exists in the destination schema, skip it (leave
-- the preexisting table alone). This is the default, but it does not hurt
-- to specify it explicitly.
DBMS_DATAPUMP.SET_PARAMETER(h1,'TABLE_EXISTS_ACTION','SKIP');
-- Start the job. An exception is returned if something is not set up properly.
DBMS_DATAPUMP.START_JOB(h1);
-- The import job should now be running. In the following loop, the job is
-- monitored until it completes. In the meantime, progress information is
-- displayed. Note: this is identical to the export example.
percent_done := 0;
job_state := 'UNDEFINED';
while (job_state != 'COMPLETED') and (job_state != 'STOPPED') loop
dbms_datapump.get_status(h1,
dbms_datapump.ku$_status_job_error +
dbms_datapump.ku$_status_job_status +
dbms_datapump.ku$_status_wip,-1,job_state,sts);
js := sts.job_status;
-- If the percentage done changed, display the new value.
if js.percent_done != percent_done
then
dbms_output.put_line('*** Job percent done = ' ||
to_char(js.percent_done));
percent_done := js.percent_done;
end if;
-- If any work-in-progress (WIP) or Error messages were received for the job,
-- display them.
if (bitand(sts.mask,dbms_datapump.ku$_status_wip) != 0)
then
le := sts.wip;
else
if (bitand(sts.mask,dbms_datapump.ku$_status_job_error) != 0)
then
le := sts.error;
else
le := null;
end if;
end if;
if le is not null
then
ind := le.FIRST;
while ind is not null loop
dbms_output.put_line(le(ind).LogText);
ind := le.NEXT(ind);
end loop;
end if;
end loop;
-- Indicate that the job finished and gracefully detach from it.
dbms_output.put_line('Job has completed');
dbms_output.put_line('Final job state = ' || job_state);
dbms_datapump.detach(h1);
END;
/
この例では、Data Pump APIを使用した簡単なスキーマ・エクスポートを示します。例5-1の延長で、例外処理機能を使用してSUCCESS_WITH_INFOケースを捕捉する方法およびGET_STATUSプロシージャを使用したエラーの詳細を取得する方法を示します。ハンドルを取得せずに現時点までの状態を取得する場合は、DBMS_DATAPUMP.GET_STATUSにNULLを指定できます。
CONNECT SYSTEM/password
DECLARE
ind NUMBER; -- Loop index
spos NUMBER; -- String starting position
slen NUMBER; -- String length for output
h1 NUMBER; -- Data Pump job handle
percent_done NUMBER; -- Percentage of job complete
job_state VARCHAR2(30); -- To keep track of job state
le ku$_LogEntry; -- For WIP and error messages
js ku$_JobStatus; -- The job status from get_status
jd ku$_JobDesc; -- The job description from get_status
sts ku$_Status; -- The status object returned by get_status
BEGIN
-- Create a (user-named) Data Pump job to do a schema export.
h1 := dbms_datapump.open('EXPORT','SCHEMA',NULL,'EXAMPLE3','LATEST');
-- Specify a single dump file for the job (using the handle just returned)
-- and a directory object, which must already be defined and accessible
-- to the user running this procedure.
dbms_datapump.add_file(h1,'example3.dmp','DMPDIR');
-- A metadata filter is used to specify the schema that will be exported.
dbms_datapump.metadata_filter(h1,'SCHEMA_EXPR','IN (''HR'')');
-- Start the job. An exception will be returned if something is not set up
-- properly.One possible exception that will be handled differently is the
-- success_with_info exception. success_with_info means the job started
-- successfully, but more information is available through get_status about
-- conditions around the start_job that the user might want to be aware of.
begin
dbms_datapump.start_job(h1);
dbms_output.put_line('Data Pump job started successfully');
exception
when others then
if sqlcode = dbms_datapump.success_with_info_num
then
dbms_output.put_line('Data Pump job started with info available:');
dbms_datapump.get_status(h1,
dbms_datapump.ku$_status_job_error,0,
job_state,sts);
if (bitand(sts.mask,dbms_datapump.ku$_status_job_error) != 0)
then
le := sts.error;
if le is not null
then
ind := le.FIRST;
while ind is not null loop
dbms_output.put_line(le(ind).LogText);
ind := le.NEXT(ind);
end loop;
end if;
end if;
else
raise;
end if;
end;
-- The export job should now be running. In the following loop, we will monitor
-- the job until it completes. In the meantime, progress information is
-- displayed.
percent_done := 0;
job_state := 'UNDEFINED';
while (job_state != 'COMPLETED') and (job_state != 'STOPPED') loop
dbms_datapump.get_status(h1,
dbms_datapump.ku$_status_job_error +
dbms_datapump.ku$_status_job_status +
dbms_datapump.ku$_status_wip,-1,job_state,sts);
js := sts.job_status;
-- If the percentage done changed, display the new value.
if js.percent_done != percent_done
then
dbms_output.put_line('*** Job percent done = ' ||
to_char(js.percent_done));
percent_done := js.percent_done;
end if;
-- Display any work-in-progress (WIP) or error messages that were received for
-- the job.
if (bitand(sts.mask,dbms_datapump.ku$_status_wip) != 0)
then
le := sts.wip;
else
if (bitand(sts.mask,dbms_datapump.ku$_status_job_error) != 0)
then
le := sts.error;
else
le := null;
end if;
end if;
if le is not null
then
ind := le.FIRST;
while ind is not null loop
dbms_output.put_line(le(ind).LogText);
ind := le.NEXT(ind);
end loop;
end if;
end loop;
-- Indicate that the job finished and detach from it.
dbms_output.put_line('Job has completed');
dbms_output.put_line('Final job state = ' || job_state);
dbms_datapump.detach(h1);
-- Any exceptions that propagated to this point will be captured. The
-- details will be retrieved from get_status and displayed.
exception
when others then
dbms_output.put_line('Exception in Data Pump job');
dbms_datapump.get_status(h1,dbms_datapump.ku$_status_job_error,0,
job_state,sts);
if (bitand(sts.mask,dbms_datapump.ku$_status_job_error) != 0)
then
le := sts.error;
if le is not null
then
ind := le.FIRST;
while ind is not null loop
spos := 1;
slen := length(le(ind).LogText);
if slen > 255
then
slen := 255;
end if;
while slen > 0 loop
dbms_output.put_line(substr(le(ind).LogText,spos,slen));
spos := spos + 255;
slen := length(le(ind).LogText) + 1 - spos;
end loop;
ind := le.NEXT(ind);
end loop;
end if;
end if;
END;
/
|
 Copyright © 2005 Oracle Corporation. All Rights Reserved. |
|