Skip to main content

This documentation is for an older version of this product. See the latest version of this content.Opens in a new tab

InterSystems IRIS での DataMove の使用法

このドキュメントでは、DataMove プロセスを使用して、InterSystems IRIS® データ・プラットフォームのネームスペースに関連付けられている既存のデータを新しい場所に移動する方法を説明します。

Important:

DataMove は、実働環境で使用する前に、特定のネームスペースおよびデータベースを使用してテスト環境でテストしておくことを強くお勧めします。

Note:

このドキュメントに記載されている 1 行のコードは、ページ・サイズやフォント・サイズによっては折り返されて複数行にまたがっている場合があります。

DataMove の概要

DataMove プロセスでは、以下の操作を実行することで、InterSystems IRIS ネームスペースに関連付けられている既存のデータを別のデータベースに移動できます。

  • ネームスペースに新しいマッピングを作成する。

  • マッピングの変更を分析し、移動する必要があるグローバルおよびグローバル添え字を計算する。

  • データを新しい 1 つ以上のデータベースにコピーする。

  • マッピングの変更を有効にする。

例えば、DataMove を使用すると、グローバルの一部または全部をネームスペースの既定のグローバル・データベースから別のデータベースに移動できます。DataMove プロセスは、ネームスペースのグローバルをルーチンとは別のデータベースに移動する、複数のデータベースにまたがるデータを分割する、アプリケーションの進化に伴って更新された設計上の決定事項に基づいて新しい場所にデータを移動するなどの操作に使用できます。DataMove を使用すると、アプリケーションでデータをアクティブに使用しながら、同じデータを移動し、マッピングを変更できます。

マッピングの詳細は、"システム管理ガイド" の “ネームスペースへのグローバル、ルーチン、およびパッケージ・マッピングの追加” を参照してください。

非推奨になっている API とその代替機能については、以下の "非推奨の呼び出しと State" を参照してください。

DataMove の制限事項

DataMove プロセスには以下の制限事項が適用されます。

  • DataMove は、同一インスタンス上のデータベース間でデータを移動するよう設計されています。ミラーリングされたシステムおよび ECP クライアントが接続されたシステムには、操作上の特別な注意が必要です。

  • DataMove は、拡張グローバル参照を使用するアプリケーションでは使用できません。アプリケーションでマッピングと拡張参照が混在している場合、データ統合は保証されません。

  • システムでジャーナリングが有効になっている必要があります。

  • ジャーナル・エラー発生時にフリーズするスイッチが設定されている必要があります。

  • データを移動できるのは、ローカル・データベース間およびミラーリングされたデータベース間のみです。

  • ミラーリングされたデータベースを含む DataMove では、プライマリ・ノードでのみ DataMove を実行できます。

  • DataMove がプライマリ・ミラーで実行されているときに、フェイルオーバーまたは DR ノードがプライマリになった場合、DataMove は停止されます。DataMove が実行されているノードが再びプライマリになった場合、DataMove は停止した箇所から再開されます。

拡張グローバル参照の詳細は、"ObjectScript の使用法" の “ネームスペース” を参照してください。

DataMove ワークフロー

DataMove ワークフローは、以下のフェーズで構成されています。

  1. ネームスペースのマッピングに対する変更が一時ストレージ領域に保存されます。

  2. 一連のデータの移動がマッピングから生成されます。

  3. データの移動が、指定されたグローバルおよびデータベースに対して検証され、移動先のデータベースに十分なディスク空き容量があることが確認されます。何らかの問題が検出された場合、ユーザはそれを修正して、ワークフローを再開できます。

  4. DataMove が開始されると、複数のバックグラウンド・ジョブが既存のデータを新しい場所にコピーします。データがコピーされると、他のバックグラウンド・ジョブがジャーナル・ファイルを処理して、コピーされたデータに変更を適用します。

  5. データのコピーがすべて完了し、ジャーナルが適用されると、ネームスペースで新しいマッピングが有効化されます。

  6. ネームスペースへの変更が正常に有効化された後は、新しい場所にコピーされた古いソース・データを削除できます。

DataMove では、すべての処理のログ・ファイル DataMoveName.log/mgr ディレクトリに保持されます。また、以前のすべての操作のレコードが /mgr ディレクトリの DataMove.log ファイルにあります。

ミラー環境または ECP 環境での DataMove

ECP 環境またはミラー環境で DataMove を使用する場合、新しいネームスペース・マッピングが ECP クライアントおよびミラーで更新されていることを確認してください。ミラー環境の場合に、新規作成したミラーリングされたデータベースにデータを移動するには、これらのミラーリングされたデータベースをバックアップ・ミラーと非同期ミラーにも作成する必要があります。

  1. DataMove を作成し、その DataMove で新しいマッピングを有効化する準備が整うまで DataMove を実行します。

  2. フェイルオーバー・ミラーを使用している場合は、有効化する前にバックアップを DR ミラーに降格させる必要があります。

  3. ECP クライアントを使用している場合は、有効化する前に、そのクライアント上のアプリケーションを停止するか、ECP システムをダウン状態にする必要があります。

  4. 非同期ミラーを使用している場合は、有効化する前に、そこにあるデータにアクセスするすべてのアプリケーションを停止するか、そこに直接接続しているすべての ECP クライアントを停止する必要があります。

  5. この時点で、新しい DataMove マッピングを有効化できます。

  6. 非同期ミラー上のマッピングを、適用したばかりの新しい DataMove マッピングに一致するよう更新します。これには、以前のバックアップ・フェイルオーバー・ミラーも含まれます。

  7. 以前のバックアップ・ミラーを DR ミラーからフェイルオーバー・ミラーに昇格させます。

  8. ECP クライアントを、適用したばかりの新しい DataMove マッピングで更新します。

  9. 非同期ミラーと ECP クライアントでのアプリケーションの再起動を許可します。

DataMove API

このセクションでは、DataMove ワークフローの各フェーズで必要な API 呼び出しについて詳しく説明します。

以下のガイドラインをメモしておいてください。

  • 特定の要件に合わせて、必要なスクリプトやユーザ・インタフェースを指定する必要があります。

  • 必要なマクロを利用するには、コードに %syDataMove ファイルをインクルードする必要があります。

  • コードでは、次の API 呼び出しに進む前に、各メソッドから返されるステータスを確認する必要があります。

  • 移動先データベースが存在しない場合は、DataMove API を呼び出す前に作成する必要があります。

  • ワークフローは、%SYS ネームスペースで実行する必要があります。

Important:

DataMove を実行する前に、システムの現在のフル・バックアップを作成しておくことをお勧めします。

DataMove ネームスペース・マッピングの作成と編集

DataMove.API.MapInitialize(Name as %String, Namespaces As %String) As %Status

新しい一連のマッピング編集用の一時ストレージ領域を初期化します。

引数 :

  • Name は、DataMove の名前です。

  • Namespaces は、DataMove を実行するネームスペースのコンマ区切りリストです。

このメソッドは、あらゆる編集を加える前に呼び出す必要があり、指定したネームスペースに対してのみ有効です。複数のネームスペースで、同じ DataMove の一部としてデータを移動できます。

Caution:

このメソッドを呼び出すことによって一時ストレージ領域内の既存の編集が削除されます。一時ストレージ領域は、DataMove API による変更および管理ポータルの [グローバルマッピング] ページを使用する変更を含め、すべてのネームスペースでのすべてのマッピング変更に使用されます ("システム管理ガイド" の “InterSystems IRIS の構成” の章にある "グローバル・マッピング" を参照してください)。同時マッピング変更によってエラーを生じさせないために、MapInitialize() を呼び出す際はどのネームスペースに対してもマッピング変更が進行していないこと、および DataMove プロセスが完了するまで他のマッピング変更が開始されないことを確認する必要があります。

例 :

Set Namespace = "SALES"
Set Status = ##Class(DataMove.API).MapInitialize("DMName",Namespace)
If '$$$ISOK(Status) Write !,$SYSTEM.Status.GetErrorText(Status)

例 :

Set Namespaces = "SALES,PROSPECTS"
Set Status=##Class(DataMove.API).MapInitialize("DMName",Namespaces)
If $$$ISOK(Status) Write !,$SYSTEM.Status.GetErrorText(Status)

DataMove.API.MapGlobalsCreate(Name as %String, Namespace As %String, GblName As %String, ByRef Properties As %String) As %Status

一時ストレージ領域に、このネームスペースの新しいグローバル・マッピングを作成します。このメソッドは、この DataMove に含める予定のマッピングの数に応じて、1 回以上呼び出すことができます。

引数 :

  • Name は、DataMove の名前です。

  • Namespace は、DataMove を実行するネームスペースです。

  • GblName は、特定のデータベースにマッピングするグローバルの名前です。

  • Properties は、このマッピングに必要なプロパティ (特にこのマッピングで使用するデータベースの名前) の配列です。

Name 引数を “A” に設定すると、このマッピングをグローバル ^A 全体に適用することが指定されます。この引数を “"A(5):A(10)"” に設定すると、このマッピングを ^A(5) から ^A(10) まで (ただし ^A(10) は含まない) の添え字付きのグローバル範囲に適用することが指定されます。

Properties 引数を、Properties("Database") が “USER2” に設定される配列 Properties に設定すると、グローバル (またはグローバル範囲) がデータベース USER2 にマッピングされることが指定されます。

マッピングを変更または削除するには、それぞれ MapGlobalsModify() メソッド、API.MapGlobalsDelete() メソッドを使用できます。 詳細は、"クラス・リファレンス" を参照してください。

例 :

Set Properties("Database")="DSTDB"

;Move ^X(100) up to but not including ^X(200) to database DSTDB
Set Status = ##Class(DataMove.API).MapGlobalsCreate("DMName","SALES","X(100):(200)",.Properties)

;Move the entire ^INFO global to database DSTDB
Set Status = ##Class(DataMove.API).MapGlobalsCreate("DMName","SALES","INFO",.Properties)

;Move all Data from the first subscript in ^BILLING 
;(including the node ^BILLING itself) up to but not including ^BILLING(100) 
;to database DSTDB
Set Status = ##Class(DataMove.API).MapGlobalsCreate("DMName","SALES","BILLING(BEGIN):(100)",.Properties)

;Move the entire global ^PROSPECT 
;from its currently mapped database to DSTDB
Set Status = ##Class(DataMove.API).MapGlobalsModify("DMName","SALES","PROSPECT",.Properties)

;Move the entire global ^ORDERS from its currently mapped database 
;back to the default database for the namespace SALES
Set Status=##Class(DataMove.API).MapGlobalsDelete("DMName","SALES","ORDERS")

グローバル範囲を定義する方法の詳細は、"システム管理ガイド" の "グローバル・マッピング" を参照してください。

DataMove の生成

DataMove.API.Generate(Name As %String, ByRef Properties As %String, ByRef Warnings As %String, ByRef Errors As %String) As Status

一時ストレージ領域のマップ編集に基づいて新しい DataMove を作成します。

引数 :

  • Name は、作成する DataMove の名前です。

  • Properties は、DataMove の作成に使用するオプションのプロパティの配列です。

  • Warnings は、DataMove の実行を阻止することはない競合を含んで返される配列です。

  • Errors は、DataMove の実行を阻止する競合を含んで返される配列です。

Properties が、Properties 引数として渡される配列の場合、次のようになります。

  • Properties("MaxMBPerMin") では、DataMove 処理で移動先データベースに移動できる 1 分あたりの最大 MB 数をオプションで指定します。これを 0 に設定すると、DataMove は可能な限り高速で実行されます。これを渡さない場合は、システムの既定値が使用されます。

  • Properties("Description") では、オプションで実行対象の DataMove の説明を指定します。

  • Properties("Flags") では、オプションで DataMove 処理を説明する以下のようなフラグを指定します。

    • $$$BitNoSrcJournal、ジャーナリングされないデータベースをコピーできます。

    • $$$BitNoBatchMode、バッチ・モードを使用せずにデータ・コピーを実行します。

    • $$$BitCheckActivate、マッピングの変更を有効にする前に、ユーザ指定のルーチン $$CheckActivate^ZDATAMOVE() を呼び出して、アプリケーションのステータスを確認します。

  • Properties("LogFile") では、オプションで、既定値以外の場合にログ・ファイル名を指定します。

Warnings 配列には、移動するデータが別のネームスペースからもマッピングされている場合にマッピングのリストが含まれます。この配列には、グローバルまたはグローバル範囲の名前が添え字として付きます。

Errors 配列には、競合によってデータの移動が阻止されるマッピングのリストが含まれます。この配列には、グローバルまたはグローバル範囲の名前が添え字として付きます。

例 :

Set Properties("Flags")= $$$BitCheckActivate
Set Status=##Class(DataMove.API).Generate("TEST",.Properties,.Warnings,.Errors)

データベースのジャーナリングの詳細は、"データ整合性ガイド" の “ジャーナリング” を参照してください。

バッチ・モードでのプロセスの実行の詳細は、"専用のシステム/ツールおよびユーティリティ" の “プロセス管理” を参照してください。

DataMove の開始

DataMove.API.StartCopy(Name As %String) As %Status

DataMove コピーを開始します。これにより、実際のデータ移動が処理されます。

引数 :

  • Name は、DataMove の名前です。

このメソッドによって DataMove の最初のコピーが一連のバックグラウンド・ジョブとして開始され、これらのジョブによって個々の範囲が移動元データベースから移動先データベースにコピーされます。それと同時に、コピー時に変更されるデータの移動先データベースにジャーナル・トランザクションが適用されます。

コピーが実際に始まる前に、StartCopy() によって Validate() および ValidateSizes() が呼び出され、DataMove が検証されます。検証でエラーが返された場合、StartCopy() は検証エラーを返し、DataMove を開始しません。ユーザはエラーを修正してから、StartCopy() を再度呼び出すことができます。

DataMove の監視

DataMove.API.GetProperties(Name As %String, ByRef Properties as %String) As %Status

DataMove の現在のプロパティを返します。

引数 :

  • Name は、DataMove の名前です。

  • Properties は、以下のような DataMove プロパティの配列です。

    • Properties("ExpandedState") – 状態の展開された外部形式。

    • Properties("JRNMBToApply") – 処理対象のジャーナル・ファイルの現在の MB 数 = 0。

    • Properties("MaxMBPerMin") – DataMove で移動が許可されている 1 分あたりの最大 MB 数。

    • Properties("MBCopied") – コピー済みの MB 数。DataMove の終了時、すべてのデータがコピーされ、Activate() が呼び出される前、コピーされた MB 数は、ソース・データベースのデータが DataMove の実行中に更新されるシステムの MBToCopy の MB 数とは一致しない可能性があります。

    • Properties("MBToCopy") – コピー対象のおおよその MB 数。

    • Properties("State") – 移動の現在の状態。以下の表を参照してください。

    • Properties("StateExternal")State プロパティの外部形式。

    • Properties("Status") – 発生したエラーの %Status の値。

    • Properties("Stop") – DataMove の停止状態 :

      • $$$DMStopNone – 停止のシグナルなし。

      • $$$DMStopNormal – Activate() メソッドによって呼び出されたときに、停止のシグナルが送信されました。

      • $$$DMStopShutdown – 通常のシステム・シャットダウンにより停止のシグナルが送信されました。システム起動時に再起動するパラメータが設定されている場合、DataMove はシステム再起動時に再開します。

      • $$$DMStopUser – ユーザのメソッド StopCopy() の呼び出しにより、停止のシグナルが送信されました。コピーは、StartCopy() によって再開できます。

      • $$$DMStopForce – Force() によって停止のシグナルが送信されました。コピーは、StartCopy() によって再開できます。

      • $$$DMStopErrorRecoverable – エラーにより停止のシグナルが送信されました。エラーの修正後に、StartCopy() によってコピーを再開できます。

      • $$$DMStopErrorUnRecoverable – 回復不能エラーにより停止のシグナルが送信されました。これはジャーナル・エラーなど複数の異なる原因による可能性があります。ここで実行できる唯一の方法は、Rollback() を呼び出してから StartCopy() を呼び出して DataMove を再起動するか、Delete() を呼び出して DataMove を削除することです。

例 :

%SYS>Set x=##Class(DataMove.API).GetProperties("ABC1",.Properties)

%SYS>Zwrite Properties
Properties("JRNMBToApply")=0
Properties("MaxMBPerMin")=1200
Properties("MBCopied")=17030.67
Properties("MBToCopy")=20034.44
Properties("State")=6
Properties("StateExternal")="Copy"
Properties("Status")=1
Properties("Stop")=0

^DATAMOVE ユーティリティ

^DATAMOVE ユーティリティは、システムに定義されているすべての DataMove の現在の状態を表示します。ユーザはこれを使用して DataMove の既定のパラメータを設定できます。一度に 1 つの DataMove のみ実行できます。

DataMove の既定のパラメータの設定

DataMove の既定のシステム・パラメータを使用して、システムの再起動時に実行する処理を指定できます。また、1 分あたりに移動するデータの量を制限することもできます。既定で、実行中の DataMove は可能な限り高速にデータをコピーします。ただし、これによりシステム上の他のユーザ・プロセスや、ミラー・システムの遅延に影響が及ぶ可能性があります。

%SYS>d ^DATAMOVE
1) Monitor DataMove
2) Edit DataMove settings
3) Exit
Option? 2

Restart DataMove after normal system shutdown? Yes => Yes
Restart DataMove after system crash? Yes => Yes

Setting the maximum number of MB DataMove is allowed to copy per minute 
to 0 means that DataMove will copy the data as fast as it can. Changing 
this setting will apply the new value to future DataMoves, and optionally 
any currently running DataMoves. You can also change this setting through 
the 'Metrics' display screen for a running DataMove without changing the 
system default.
Maximum number of MB to copy per minute? 0 => 1200
Do you want to apply this change to existing Data Moves? Yes => Yes
Confirm changes? Yes => Yes
DataMove settings updated

1) Monitor DataMove
2) Edit DataMove settings
3) Exit

DataMove の監視

Generate() メソッドを呼び出した後は、^DATAMOVE を使用して、移動の状態および移動対象として設定されている範囲を確認できます。

%SYS>d ^DATAMOVE
1) Monitor DataMove
2) Edit DataMove settings
3) Exit
Option? 1

これは、Generate() および StartCopy() を呼び出した後に表示される内容の例です。これは、DataMove 内のすべての移動対象範囲の累積統計データを示しています。

The utility show numerous fields that hold aggregated information about the DataMove.

これらのフィールドは、以下の情報を示しています。

  • Jrn Cycle Time – ジャーナル・スキャナまたはジャーナルの適用において、前回ジャーナルの末尾に達したときから、現在のジャーナル・ファイルの末尾に達するまでにかかった時間。

  • First Jrn Time – ジャーナル・スキャナまたはジャーナルの適用において、初めて現在のジャーナル・ファイルの末尾に達するまでにかかった時間。

  • CopyTime – グローバルのコピーにかかった時間。

  • Size Time – グローバルのサイズの計算にかかった時間。

  • Done – ジャーナル・ファイル内で検出された各操作のうち、移動先データベースに適用されたものの総数。

  • Avoid – ジャーナル・ファイル内で検出された各操作のうち、スキップ可能だったものの総数。コピーがまだ開始していない場合、操作をスキップできます。コピーが開始していた場合は、移動先にまだコピーされていないグローバルの一部で操作が実行されます。

  • Copy – コピーの実行中に移動先データベースに適用された各操作の総数。

  • Journal Start – DataMove が開始されたジャーナル・ファイルとオフセット。

  • Journal Current – 現在のジャーナル・ファイルとオフセット。

  • Max MB/Min – DataMove でコピーが許可されている 1 分あたりの最大 MB 数。これを DataMove に設定するには、以下の 3 つの方法のいずれかを使用します。

    • ^DATAMOVE に指定されている DataMove の既定値

    • 以下に示している [メトリック] 画面

    • Modify() API

  • MB/Min – DataMove の生存期間中に DataMove がコピーした 1 分あたりの MB 数。

  • Blks Copied – コピーされたデータベース・ブロックの実際の数と、事前フェッチされたブロックの割合。

  • JRN Count/Size – 対象の DataMove について、現在のジャーナル・ファイル、および StartCopy() が呼び出される前の前回のジャーナル・ファイルで検出されたトランザクションの数と合計サイズ。

  • Pid Move/Jrn – コピーおよびデジャーナルを処理する 2 つのプロセスのプロセス ID。

  • Pid Copy – マスタ DataMove プロセスのプロセス ID。

範囲オプションを選択した場合、移動対象のグローバルの範囲が 5 つあることがわかります。

The utility shows which globals each range covers, as well as the current status for the range.

範囲の詳細画面で、各範囲の詳細を確認できます。これらは上記で説明されていますが、選択した範囲にのみ適用されます。

The utility show the same information as the aggregated screen, but for a single range.

ジョブ画面には、どのジョブがどのデータで実行されているかが示されます。

For each job, this display shows the Type, Job#, Commands, Globals, State, PID, and Range.

ここでは、ジョブ 84 が現在、範囲 X(40000000) のデータをコピーしていて、ジョブ 73 が同じ範囲でジャーナルをスキャンしていて、この範囲内で検出したトランザクションを適用していることがわかります。"Master Move" ジョブ 71 は、まだデータをコピー中のすべてのプロセスを制御します。"Master Journal" ジョブ 72 は、ジャーナルをスキャンまたは適用中のすべてのプロセスを制御します。"Master Copy" ジョブは、統計を累積し、Activate() メソッドを呼び出せるタイミングを判断します。ここに表示されるジョブ番号、コマンド、グローバル、状態、およびプロセス ID は、JOBEXAM または管理ポータルのプロセス表示に示される同じ情報に対応しています。

メトリック画面には、システム上のアクティビティと、実行中の DataMove にそのアクティビティがどの程度関係しているかが示されます。

In this example, DataMove activity is 98% of all global references per second on the system.

この例では、DataMove でコピーが許可される 1 分あたりの最大 MB 数が 0 (無制限) に設定されていることがわかります。また、DataMove がグローバル参照とジャーナル・エントリの大部分を占有していて、ミラー処理の遅延が増加する原因になっていることもわかります。

以下のように実行することで、DataMove の処理速度が低減されるよう制限できます。

Press C to change rate. This example sets the Max allowed MB Copied/Minute to 1200.

これで、処理速度が更新され、メトリックが大幅に低減されました。

In this example, DataMove activity is 98% of all global references per second on the system.

マッピング変更の有効化と DataMove の完了

DataMove.API.Activate(Name As %String, Display as %Boolean, Timeout As %Integer = 120) As %Status

DataMove を完了し、ネームスペースのマッピング変更を有効化します。

引数 :

  • Name は、DataMove の名前です。

  • Display は、進捗状況メッセージを確認する場合は 1 に設定する必要があります。

  • Timeout は、DataMove が実行を完了し、ジャーナル処理を適用する間、続行を待機する秒数です。

このメソッドにより、DataMove バックグラウンド・ジョブが停止し、ジャーナル・ファイルの処理が完了し、マッピング変更が CPF に書き込まれ、マッピング変更が有効になります。また、他のプロセスが実行を妨げないように、スイッチ 10 が一時的に設定されます。

$$$BitCheckActivate が設定されている場合、続行する前にこのメソッドによりユーザ指定のルーチン $$CheckActivate^ZDATAMOVE() が呼び出され、実行されます (存在する場合)。$$CheckActivate^ZDATAMOVE() から 1 が返されない場合、メソッドは新しいマッピングを有効にせずに終了し、DataMove は実行中のままになります。

Note:

新しいマッピングを有効にするためにスイッチ 10 が設定される直前に、ユーザ指定のルーチンが呼び出されます。このルーチンは、新しいマッピングを有効にする前に、ユーザが希望することをすべて実行できます。

スイッチ 10 の詳細は、"専用のシステム/ツールおよびユーティリティ" の “スイッチの使用法” を参照してください。

Note:

Activate() により DataMove の State プロパティがチェックされ、最初のコピーが完了し、続行する前にジャーナル適用がキャッチアップされたことが確認されます。

移動元のグローバルの削除と DataMove の完了

コピーが完了し、更新されたネームスペースが有効化されると、アプリケーション・データが正常にコピーされ、マッピングが有効化されていることを確認する必要があります。これを確認した後は、移動元にある移動済みのグローバルの削除処理に進み、DataMove を完了することができます。

DataMove.API.DeleteSourceGlobals(Name As %String) As %Status

DataMove でコピーされたグローバルを移動元ディレクトリから削除します。

引数 :

  • Name は、DataMove の名前です。

このメソッドにより、移動先データベースにコピー済みの、移動元データベース内のすべてのグローバルが削除されます。移動元のグローバルを削除するために、複数のプロセスが作成される場合があります。

DataMove.API.Finish(Name As %String) As %Status

DataMove プロセスを完了します。

引数 :

  • Name は、DataMove の名前です。

このメソッドにより、ログ・ファイルに成功または失敗のメッセージが書き込まれ、ログ・ファイルが閉じられ、DataMove の State プロパティが $$$DMStateDone に設定されます。また、ログ・ファイルがファイル DataMove.log にコピーされます。このファイルは、システムで実行されたすべての DataMove の記録です。

DataMove.API.Delete(Name As %String) As %Status

DataMove プロセスをクリーンアップします。

引数 :

  • Name は、DataMove の名前です。

このメソッドにより、DataMove が削除され、一時ストレージがクリーンアップされます。

削除したい DataMove 処理が開始されてから停止した場合は、まず Rollback() メソッドを呼び出して、移動されていたデータがあればそれをロールバックします。

その他の API 呼び出し

DataMove.API.Validate(Name As %String) As %Status

DataMove を検証します。

引数 :

  • Name は、DataMove の名前です。

DataMove の検証には、指定したマッピングすべての確認、移動元および移動先のデータベースの確認、移動先のグローバルがまだ存在していないことの確認が含まれます。何らかのエラーが発生した場合は Status で報告されます。

Validate() は、StartCopy() の一部として呼び出されます。このメソッドを使用して、StartCopy() でコピーを実際に開始する前に DataMove を検証できます。

DataMove.API.Modify(Name as %String, byref Properties as %String) as %Status

既存のまたは実行中の DataMove に変更を加えます。

引数 :

  • Name は、DataMove の名前です。

  • Properties は、変更するプロパティの配列で、以下が含まれる可能性があります。

    • Properties("MaxMBPerMin") - DataMove 処理で移動先データベースに移動できる 1 分あたりの最大 MB 数。これを 0 に設定すると、DataMove は可能な限り高速で実行されます。実行中の DataMove に対してこれを呼び出して、処理速度を変更することができます。

DataMove.API.ValidateSizes(Name As %String) As %Status

DataMove によってコピー対象に指定されたデータに対し、十分な容量が存在することを確認します。

引数 :

  • Name は、DataMove の名前です。

DataMove のサイズの検証には、コピーするデータ量の特定、および移動先データベースに十分な容量があることの確認が含まれます。何らかのエラーが発生した場合は Status で報告されます。

ValidateSizes() は、StartCopy() の一部として呼び出されます。このメソッドを使用して、StartCopy() でコピーを実際に開始する前に DataMove のサイズ要件を検証できます。

DataMove.API.StopCopy(Name As %String) As %Status

DataMove コピー・ジョブを停止します。

引数 :

  • Name は、DataMove の名前です。

このメソッドにより、DataMove コピー・バックグラウンド・ジョブが停止し、進行中のコピーを適切に停止できるようになります。DataMove の再起動は、StartCopy() を使用して行えます。

DataMove.API.Rollback(Name As %String) As %Status

DataMove をロールバックします。

引数 :

  • Name は、DataMove の名前です。

このメソッドにより、DataMove コピー・ジョブによって移動先データベースにコピーされたグローバルがすべて削除されます。このメソッドは、DataMove の中止またはコピー・プロセスでのエラーからの回復に使用できます。

このメソッドを呼び出す前に StopCopy() を実行する必要があります。

ロールバックの実行後は、StartCopy() を使用してやり直すことも、Delete() を使用して Data Move を削除することもできます。

DataMove.API.RollbackMappings(Name As %String)

DataMove マッピングをロールバックします。

引数 :

  • Name は、DataMove の名前です。

これにより、システムのマッピングが DataMove Name の実行前の状態に復元されます。DataMove Name の State が $$$DMStateNSPActivateDone である必要があります。この使用例として、DataMove でマッピングが有効化された後にアプリケーションのテストを開始し、何らかの問題が検出された場合が考えられます。マッピングが以前の値に復元されると、State は $$$DMStateJrnApplyDone に設定されます。その後で、Rollback() を呼び出すか (推奨)、StartCopy() を呼び出して有効化を再試行することができます。

DataMove.API.RollbackCopy(Name As %String, Warnings as %String, Errors as %String)

DataMove のコピーをロールバックします。

引数 :

  • Name は、DataMove の名前です。

  • Warnings は、DataMove の実行を阻止することはない競合を含んで返される配列です。

  • Errors は、DataMove の実行を阻止する競合を含んで返される配列です。

これにより、Name-ROLLBACK という名前の DataMove が作成されます。この DataMove を実行すると、DataMove Name でコピーされたデータが、元の移動元ディレクトリに戻されます。DataMove Name の State は $$$DMStateDeleteSrcGlobalsDone である必要があります (移動元のグローバルはすべて DeleteSourceGlobals() メソッドによって削除されています)。このメソッドが完了すると、StartCopy() および Activate() を実行して、データを元のディレクトリに戻すことができます。これにより、DataMove Name の State は $$$DMStateRollbackCopy に設定されます。

Query DataMove.API.ListDMs(Names As %String, Flags as %Integer=0) As %Status

すべての DataMove およびそのプロパティのリストを返すクエリ。

引数 :

  • Names は、DataMove のコンマ区切りのリストです。

  • フラグ –

    • 0 = DataMove レコードに記録されている現在の情報を返します。

    • 1 = すべての範囲をまとめた情報を返します。

Query DataMove.API.ListRanges(Name As %String, SrcDBs As %String = "*", DstDBs As %String = "*", Ranges As %String = "*", Flags = 0) As %Status

すべての DataMove 範囲およびそのプロパティのリストを返すクエリ。

引数 :

  • Names は、DataMove の名前です。

  • SrcDBs – 移動元データベースのコンマ区切りのリスト

  • DstDBs – 移動先データベースのコンマ区切りのリスト

  • Ranges – 範囲のコンマ区切りのリスト

  • フラグ –

    • 0 = フォーマットされた時刻を返します。

    • 1 = $h UTC 時刻として時刻を返します。

Query DataMove.API.ListProcesses(Name As %String) As %Status

すべての DataMove プロセスのリストを返すクエリ。

引数 :

  • Name は、DataMove の名前です。

DataMove の状態

DataMove では、State プロパティを使用して、ワークフロー全体を通して進捗状況が記録されます。GetProperties() を使用することで、このプロパティを調べて、進捗状況を監視できます。問題が生じた場合は、クエリ ListDMs() を使用して、トラブルシューティングすることができます。

各 State の整数値は、%syDataMove.inc インクルード・ファイルで定義されています。

DataMove の State のリスト
State 説明
$$$DMStateNotStarted DataMove を作成するために Generate() が呼び出されました。
$$$DMStateStarted コピーを開始するために StartCopy() が呼び出されました。
$$$DMStateSize 移動するデータのサイズが計算されています。
$$$DMStateSizeDone 移動するデータのサイズが計算されました。
$$$DMStateCopy ソース・データが移動先データベースにコピーされています。
$$$DMStateCopyDone ソース・データの移動先データベースへのコピーが完了しました。
$$$DMStateJrnApply すべてのソース・データが移動先データベースにコピーされ、現在ジャーナルが移動先データベースに適用されています。Activate() または StopCopy() が呼び出されるまで、またはシステムが正常にシャットダウンするまで、この状態が維持されます。
$$$DMStateJrnApplyDone Activate() または StopCopy() の呼び出し中に、DataMove プロセスが停止しました。
$$$DMStateNSPActivate Activate() が呼び出されました。スイッチ 10 が設定され、新しいネームスペース・マッピングが有効化されています。
$$$DMStateNSPActivateDone 新しいネームスペース・マッピングが有効化されました。
$$$DMStateDeleteSrcGlobals DeleteSourceGlobals() が呼び出され、移動元のグローバルが削除されています。
$$$DMStateDeleteSrcGlobalsDone 移動元のグローバルがすべて削除されました。
$$$DMStateDone Finish() が呼び出されました。すべてのデータが移動先データベースに移動され、ネームスペースが有効化され、最終的なログ・ファイルが更新されました。
$$$DMStateRollback Rollback() メソッドが呼び出され、コピーされたすべての移動先グローバルが削除されています。完了すると、State は $$$DMStateNotStarted に設定されます。
$$$DMStateRollbackCopy RollbackCopy() メソッドが呼び出されました。この DataMove は完了し、ここからデータを前の場所に戻す新しい DataMove が作成されました。

DataMove の例

ObjectScript ルーチンは、DataMover という DataMove オブジェクトを使用して、ネームスペース LIVE のグローバル ABC および DEF をデータベース LIVE-CT に移動します。

この例は、デモンストレーションを目的としているため、包括的なエラー・チェックは含まれていません。各 API 呼び出しの後に返されるステータスを確認してください。

#include %occStatus
#include %syDataMove
#include %syConfig

#; Sample routine to illustrate using DataMove to move globals.
Example() {
    #; New Mapping definition
    Set NewMap = 1
    Set NewMap(1, "name") = "ABC"
    Set NewMap(1, "db") = "LIVE-CT"
    Set NewMap = 2
    Set NewMap(2, "name") = "DEF"
    Set NewMap(2, "db") = "LIVE-CT"

    #; Let's start initializing the edits space before moving the globals
    Write "Initialize edits.........."
    Set Namespace = "LIVE"
    Set Status = ##class(DataMove.API).MapInitialize("DBNAME",Namespace)

    #; Now we need to create the new mappings
    Write "Create/Update maps.........."

    #; Main loop to define mappings and operations to be done.
    For i = 1:1:NewMap {
        Kill Obj, Name, Prop, Status
        Set Prop("Database")=NewMap(i, "db")
        Set Name=NewMap(i, "name")

        #; Write name after a new line
        Write !, Name

        #; Checking if the global exists
        Do ##Class(Config.MapGlobals).Exists(Namespace, Name, .Obj)
        If (Obj = "") {
            #; Creating the global
            Write !, "  - Create.........."
            Set Status = ##class(DataMove.API).MapGlobalsCreate("DBNAME",Namespace,Name,.Prop)
        } Else {
            #; Modifying the global
            Write !, "  - Modify.........."
            Set Status = ##class(DataMove.API).MapGlobalsModify("DBNAME",Namespace,Name,.Prop)
        }
    }

    #; We have everything set up, now we need to create the DM object
    Write "Create DM.........."
    Set Status = ##class(DataMove.API).Generate("DBNAME",.Properties, .Warnings, .Errors)
    If $data(Warnings) Write ! Zwrite Warnings
    If $data(Errors) Write ! Zwrite Errors

    #; Creating the background job that needs to be run
    Write "Creating the JOB.........."
    Set Status = ##class(DataMove.API).StartCopy("DBNAME")

    #; Monitor the DataMove until we can activate it.
    For {
        #; Monitor state every 5 seconds
        Hang 5
        Set Status=##Class(DataMove.API).GetProperties("DBNAME",.Properties)
        #; Activate will only run if we are applying journals and have 5 MB or less of journal to apply.
        If (Properties("State")=$$$DMStateJrnApply) {
            If (Properties("JRNMBToApply")<=5) {
                Quit
            }
        }
        Write !,"MB to copy: "_Properties("MBToCopy")
        Write !,"MB copied: "_Properties("MBCopied")
        Write !,"Journal MB still to apply: "_Properties("JRNMBToApply")
    }
    Write !, "Activating the new Mappings..."
    Set Display=1
    Set Status=##Class(DataMove.API).Activate("DBNAME",Display)
    
    #; Delete the source globals that have been copied in the DataMove
    Write "Deleting the old Globals......."
    Set Status = ##class(DataMove.API).DeleteSourceGlobals("DBNAME")

    #; Stopping the DataMover
    Write "Closing the DataMover......."
    Set Status = ##class(DataMove.API).Finish("DBNAME")

    #; Delete the DataMove and clean up any temporary storage
    Write "Deleting the DataMover......."
    Set Status = ##class(DataMove.API).Delete("DBNAME")
}

非推奨の呼び出しと State

呼び出しと State の両方に変更が加えられています。以下の 2 つの表は、古い非推奨の呼び出しと State、およびそれに関連付けられている代替の呼び出しと State をリストしています。

非推奨および新規の DataMove の呼び出しのリスト
古い名前 新しい名前
Config.Map.InitializeEdits DataMove.API.MapInitialize
Config.MapGlobals.Create DataMove.API.MapGlobalsCreate
Config.MapGlobals.Delete DataMove.API.MapGlobalsDelete
Config.MapGlobals.Modify DataMove.API.MapGlobalsModify
Config.Map.Revert(0) DataMove.API.RollbackCopy
Config.Map.Revert(1) DataMove.API.RollbackMappings
DataMove.Data.Activate DataMove.API.Activate
DataMove.Data.CreateFromMapEdits DataMove.API.Generate
DataMove.Data.Dispatch(Name, "Delete") DataMove.API.Delete
DataMove.Data.Dispatch(Name, "DeleteSrcGlobals") DataMove.API.DeleteSourceGlobals
DataMove.Data.Dispatch(Name, "Finish") DataMove.API.Finish
DataMove.Data.Dispatch(Name, "Rollback") DataMove.API.RollBack
DataMove.Data.Dispatch(Name, "Validate") DataMove.API.Validate
DataMove.Data.Dispatch(Name, "ValidateSizes") DataMove.API.ValidateSizes
DataMove.Data.DispatchJob(Name, "Copy") DataMove.API.StartCopy
DataMove.Data.Display() ^DATAMOVE
DataMove.Data.Exists 代替の呼び出しなし
DataMove.Data.StopCopy DataMove.API.StopCopy
非推奨および新規の DataMove の State のリスト
古い State 新しい State
$$$Copy $$$DMStateCopy
$$$CopyDone $$$DMStateCopyDone
$$$CPFUpdate 対応する State なし
$$$CPFUpdateDone 対応する State なし
$$$Delete $$$DMStateDeleteSrcGlobals
$$$Done $$$DMStateDone
$$$JrnApply $$$DMStateJrnApply
$$$JrnApplyDone $$$DMStateJrnApplyDone
$$$NotStarted $$$DMStateNotStarted
$$$NSPActivate $$$DMStateNSPActivate
$$$NSPActivateDone $$$DMStateNSPActivateDone
$$$Size $$$DMStateSize
$$$SizeDone $$$DMStateSizeDone
$$$Started $$$DMStateStarted
対応する State なし $$$DMStateRollback
対応する State なし $$$DMStateRollbackCopy
FeedbackOpens in a new tab