InterSystems IRIS での DataMove の使用法

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

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

引数 ：

• Name は、DataMove の名前です。

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

このメソッドは、あらゆる編集を加える前に呼び出す必要があり、指定したネームスペースに対してのみ有効です。複数のネームスペースで、同じ 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 は、このマッピングに必要なプロパティ (特にこのマッピングで使用するデータベースの名前) の配列です。

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

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

既存のマッピングを変更または削除するには、それぞれ MapGlobalsModify() メソッド、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.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("MaxMBCheckPerMin") では、オプションで、DataMove の DataCheck 処理でチェックできる 1 分あたりの最大 MB 数を指定します。

  これを 0 に設定すると、DataMove の DataCheck は可能な限り高速で実行されます。これを渡さない場合は、システムの既定値が使用されます。

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

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

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

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

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

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

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

例 ：

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

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

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

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

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

引数 ：

• Name は、DataMove の名前です。

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

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

コピーが完了したら、StartCopy() は DataCheck を呼び出して、コピー元とコピー先のデータが同じであることを確認します。DataCheck が正常に完了したら、Activate() を呼び出すことができます。

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("MaxMBCheckPerMin") – DataMove の DataCheck で処理できる 1 分あたりの最大 MB 数。

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

  • Properties("MBChecked") – DataCheck された MB 数。DataCheck が完了すると、この値はコピーされたデータのサイズより大きくなります。

  • 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("ExpandedState")="ActivateReady/Run"
Properties("JRNMBToApply")=0
Properties("MBChecked")=25622
Properties("MBCopied")=24722
Properties("MBToCopy")=24722
Properties("MaxMBCheckPerMin")=0
Properties("MaxMBPerMin")=0
Properties("State")=10
Properties("StateExternal")="ActivateReady"
Properties("Status")=1
Properties("Stop")=0

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

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

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

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 => 5000
Do you want to apply this change to existing Data Moves? Yes => Yes

DataMove の DataCheck でチェックできる 1 分あたりの最大 MB 数を 0 に設定すると、DataMove の DataCheck は可能な限り高速でデータをチェックします。この設定を変更すると、今後の DataMove に新しい値が適用され、オプションで現在実行中の DataMove にも新しい値が適用されます。この設定は、システムの既定を変更することなく、実行中の DataMove DataCheck の [メトリック] 表示画面でも変更できます。

Maximum number of MB to check per minute? 0 => 8000
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 内のすべての移動対象範囲の累積統計データを示しています。

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

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

• DataCheck Time – DataCheck の完了にかかった時間。

• 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 – コピーされたデータベース・ブロックの実際の数。

• Nodes Checked – DataCheck されたグローバル・ノードの数。

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

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

• Pid Copy/Chk – マスタ DataMove プロセスとマスタ DataCheck プロセスのプロセス ID。

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

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

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

"Copy" タイプのジョブは、コピー元からコピー先データベースにデータをコピーするプロセスです。"Jrn" タイプのジョブは、宛先データベースにジャーナル・トランザクションを適用します。"Chk" タイプのジョブは、コピー元データベースとコピー先データベースの間で DataCheck を実行します。ここに表示されるジョブ番号、コマンド、グローバル、状態、およびプロセス ID は、JOBEXAM または管理ポータルのプロセス表示に示される同じ情報に対応しています。

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

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

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

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

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

DataMove を完了し、ネームスペースのマッピング変更を有効化します。Activate() は、DataCheck() が完了するまで実行されません。

引数 ：

• Name は、DataMove の名前です。

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

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

• Force は、ジャーナルがキャッチアップされていない場合でもネームスペース・マッピングの有効化を開始します。Force フラグを設定すると、スイッチ 10 が設定されている間、追加で時間を費やして、有効化プロセスで最後のジャーナル・ファイルが適用されます。

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

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

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

ミラー・メンバと ECP クライアントでのマッピングの更新

システムで新しいネームスペース・マッピングを有効化したら、他のすべてのミラー・メンバと ECP クライアントでマッピングを更新できます。DataMove では、MGR ディレクトリに DataMove_DataMoveName_Actions.cpf という名前のファイルが生成されます。このファイルには、ミラーおよび ECP CPF ファイルにマージできる一連のアクションが含まれます。以下に、このファイルの形式の例を示します。

[Actions]
CreateMapGlobal:Namespace=SALES,Name=A(86048):(172095),Database=DATA
CreateMapGlobal:Namespace=SALES,Name=A(172095):(258142),Database=DATA
CreateMapGlobal:Namespace=SALES,Name=A(258142):(344189),Database=DATA
CreateMapGlobal:Namespace=SALES,Name=A(344189):(430236),Database=DATA

このファイルを詳しく見てみましょう。これには、システムの CPF ファイルに新たに適用された一連のマッピングが含まれている必要があります。このファイルを他のミラー・メンバと ECP クライアントにコピーし、iris merge コマンドを使用してマッピングをそれらのシステム上の CPF ファイルに挿入して有効化することができます。

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() メソッドを呼び出して、移動されていたデータがあればそれをロールバックします。

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 に対してこれを呼び出して、処理速度を変更することができます。

  • Properties("MaxMBCheckPerMin") – DataMove の DataCheck 処理でチェックできる 1 分あたりの最大 MB 数。これを 0 に設定すると、DataMove の DataCheck は可能な限り高速で実行されます。実行中の 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 は $$$DMStateReady に設定されます。その後で、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 の名前です。