Qレプリケーション・チュートリアル ASNCLP版（３）～Qレプリケーション環境セットアップ～

これは、**Qレプリケーション・チュートリアル ASNCLP版**の3番目の記事です。
←[前の記事(2)][Qrep_nonGUI.2] | [次の記事(4)][Qrep_nonGUI.4]→
[(1)][Qrep_nonGUI.1] | [(2)][Qrep_nonGUI.2] | [(3)][Qrep_nonGUI.3] | [(4)][Qrep_nonGUI.4] | [(5)][Qrep_nonGUI.5]

# :four_leaf_clover: <font color="MediumAquaMarine">モジュール.2</font> :four_leaf_clover:<br>　Q レプリケーションのセットアップ
**参照元:** [モジュール 2: Q レプリケーションのセットアップ- IBM Documentation][QrepTut_Module.2]

このモジュールでは、コントロール表、 レプリケーション・キュー・マップ、および Q サブスクリプションを作成します。またソース・データベースをレプリケーション・ソースにできるように、データベース・ロギングの方法を変更します。

チュートリアルではレプリケーション・センターを使用したシナリオになっていますが、ここから[**ASNCLPコマンド**](https://www.ibm.com/docs/ja/idr/11.4.0?topic=replication-asnclp-command-line-program)を使って実行する方法をご紹介します。

ASNCLPはQレプリケーションだけでなく、SQLレプリケーションの定義もできるツールです。
Qレプリケーション用のASNCLPコマンドについては、以下のサイトに情報があります。
[Q レプリケーション用の ASNCLP コマンド - IBM Documentation][asnclp_Qrep]

ASNCLPはJava 環境で稼働するため、そのためのセットアップが必要です。
詳細は以下を参照してください。
[ASNCLP プログラムを実行するための Java 環境のセットアップ (Linux、UNIX、Windows) - IBM Documentation](https://www.ibm.com/docs/ja/idr/11.4.0?topic=program-setting-up-java-environment)

ハンズオン環境では、SAMPLEデータベースもTARGETDBデータベースも、どちらもCONNECT（接続）できる状態になっているはずです。
レプリケーションの定義は、ソース側（Qキャプチャー側）とターゲット側（Qアプライ側）の情報は整合性を持って定義する必要があるため、通常はソース・データベースおよびターゲット・データベースの双方に接続（CONNECT）できる状態でASNCLPを利用します。

:::note
**ASNCLPの実行場所**
・Qレプリケーションでは、ソース表とターゲット表の初期同期を行うフルリフレッシュをDb2の機能で行う際は、ターゲット表のあるDb2インスタンスから、ソース表のあるデータベースに接続できるようにしておく必要があるので、ASNCLPの実行はターゲット側のDb2インスタンスで行うことが多いです。
・ソース側のDb2とターゲット側のDb2のレベルが異なる場合は、高い方のDb2インスタンスでASNCLPを実行することがガイドされています。
・z/OSのDb2同士の場合は、z/OS上でもASNCLPは利用できますが、使いやすさの観点から、ASNCLP用にz/OS Db2に接続できるWindowsやLinux環境を用意することもあります。
:::

以下の制御表の作成はソース・データベース側、ターゲット・データベース側を別々に作成することは可能なので、その場合は作成したいデータベースに接続できればいいですが、ここでは両方同時に作成するようにしています。

## :shamrock: <font color="MediumAquaMarine">レッスン 2.1</font> :shamrock: <br>　ソースおよびターゲットのコントロール表の作成
**参照元:** [レッスン 2.1: ソースおよびターゲットのコントロール表の作成 - IBM Documentation][Lesson2.1]

まずレプリケーションの定義情報を格納するQレプリケーションのコントロール表（制御表）を作成します。

:::note
ASNCLPを使ってQレプリケーションの制御表を作成する方法は、こちらでも紹介されていますので、参考にしてください。
[ASNCLPコマンドを使ってQレプリケーション制御表を作成する - Qiita][asnclp_qiita]（寄稿者の許可取得済み）
:::

**１．制御表作成用のASNCLPスクリプト・ファイルの作成**

:::note infp
**制御表作成のASNCLPコマンド**
・<font color="blue">Qキャプチャー用</font>
　　**CREATE CONTROL TABLES FOR CAPTURE SERVER**
・<font color="hotpink">Qアプライ用</font>
　　**CREATE CONTROL TABLES FOR APPLY SERVER**
:::
ASNCLPコマンドをまとめて実行するために、コマンドをファイルに記述します。

お好きなエディターで、以下の内容の```cre.QREP_CTRL.clpin.txt```を作成してください。
スクリプト内でキュー・マネージャー名やキュー名を指定する箇所がありますが、ASNCLPコマンドの実行時にはその妥当性チェックはしませんので、[モジュール.１][Qrep_nonGUI.2]で作成した名前を間違えないように指定してください。

:::note
一文字目が # はコメントアウトになります。
:::

```cre.QREP_CTRL.clpin.txt
## Qレプリケーション用のASNCLPセッションであることを宣言
ASNCLP SESSION SET TO Q REPLICATION;

### 生成されたSQL文を保管するファイル
 SET OUTPUT CAPTURE SCRIPT "cre.QCAP_CTRL.sql.txt";
 SET OUTPUT TARGET SCRIPT "cre.QAPP_CTRL.sql.txt";

### ASNCLPコマンドの実行ログファイル
 SET LOG "cre.QREP_CTRL.clpin.log.txt";

### SQLファイルの出力のみ（SQLファイルの内容は自分で実行する）
 SET RUN SCRIPT LATER ;

### SQLファイルの出力および即時実行
# SET RUN SCRIPT NOW STOP ON SQL ERROR ON;

### ソースおよびターゲット データベースの指定
### パスワード・ファイルを利用して、接続ユーザー情報とパスワード情報を読みこませる場合
 SET PWDFILE "asnpwd.aut";
 SET SERVER CAPTURE TO DB SAMPLE ;
 SET SERVER TARGET TO DB TARGETDB ;

### Qキャプチャー、Qアプライが使用するキュー・マネージャーの指定
 SET QMANAGER SRC_QM FOR CAPTURE SCHEMA;
 SET QMANAGER TGT_QM FOR APPLY SCHEMA;

### Qキャプチャー、Qアプライのスキーマ名（ASNはデフォルト、任意の名前を指定可能）
 SET CAPTURE SCHEMA SOURCE ASN;
 SET APPLY SCHEMA ASN;

###  Qキャプチャー用の制御表の作成　再始動キューと管理キューを指定する
 CREATE CONTROL TABLES FOR CAPTURE SERVER
  USING RESTARTQ "RESTARTQ" ADMINQ "ADMINQ" ;

### Qアプライの制御表の作成
 CREATE CONTROL TABLES FOR APPLY SERVER ;
```
このファイルを入力に、ASNCLPを実行すればよいのですが、この例ではスクリプト・ファイルの中にデータベース接続に必要なパスワードを記載しなくて良いように、事前に作成したパスワード・ファイルを利用する方法を採用しています。
そのため、先にパスワード・ファイルを作成しておきます。

**２．パスワード・ファイルの作成**
このシナリオでは、SAMPLEデータベース、およびTARGETDBデータベースには　
　ユーザーID：db2admin
　パスワード：db2adminpw
で接続するようにしていますので、その情報を登録したパスワード・ファイルを作成します。
※お使いのユーザーIDやパスワードが上記と異なる場合は、適宜変更してください。

パスワード・ファイルはASNCLPだけでなく、Qレプリケーションを動かす場合にも構成によっては必要になるものですので、作成の仕方は覚えておくとよいです。

:::note infp
**パスワード・ファイル作成コマンド**
**asnpwd**
・オプション
　　初期作成　**init**
　　ID/パスワード登録　**add**

その他のオプションについては、こちらを参照してください。
**参考:** [asnpwd: パスワード・ファイルの作成および保守 - IBM Documentation](https://www.ibm.com/docs/ja/idr/11.4.0?topic=commands-asnpwd-creating-maintaining-password-files)
:::

まず、パスワード・ファイルを作成します。
```
asnpwd init encrypt password
```

<details><summary>結果例</summary>

```
2023-xx-xx-16.09.02.010000 ASN1981I  "Asnpwd" : "" : "Initial". プログラムは、
パスワード・ファイル "asnpwd.aut" を使用して正常に完了しました。
```
</details>

:::note info
・登録したデータベースとユーザーをあとから確認できるよう、ここではパスワードだけ暗号化する指定(encrypt password)にしてパスワード・ファイルを初期生成しています。
（何も指定しない場合は、すべての項目が暗号化され、ファイル内の登録済みデータベース別名、ユーザー名をあとから確認することはできません）
・ここではasmpwdコマンドでパスワード・ファイル名を指定していないので、デフォルト名の**asnpwd.aut**ファイルが生成されますが、任意のファイル名を指定することも可能です。
:::
データベースごとに、接続するユーザーIDとパスワードを登録します。
・SAMPLEデータベース用の登録
```
asnpwd add alias SAMPLE id db2admin password db2adminpw
```

<details><summary>結果例</summary>

```
2023-xx-xx-16.14.00.715000 ASN1981I  "Asnpwd" : "" : "Initial". プログラムは、
パスワード・ファイル "asnpwd.aut" を使用して正常に完了しました。
```
</details>

・TARGETDBデータベース用の登録
```
asnpwd add alias TARGETDB id db2admin password db2adminpw
```

<details><summary>結果例</summary>

```
2023-xx-xx-16.14.27.843000 ASN1981I  "Asnpwd" : "" : "Initial". プログラムは、
パスワード・ファイル "asnpwd.aut" を使用して正常に完了しました。
```
</details>

登録したデータベース別名とユーザーIDを確認します。
```
asnpwd list
```
パスワードだけ暗号化する指定(encrypt password)にしたので、データベース名と接続に使うユーザーIDが表示されます。
```
Alias: SAMPLE  ID: db2admin
Alias: TARGETDB  ID: db2admin
Number of Entries: 2
```
このパスワード・ファイル名(ここではasnpwd.aut)をASNCLPスクリプトの中の **SET PWDFILE** で指定しています。

:::note 
SET PWDFILEでパスワード・ファイルを設定できるのは、Db2 V11.1以降に含まれるQレプリケーションからです。それより前のレベルの場合は、以下のようにASNCLPスクリプト内で接続情報を指定します。

```
### ソースおよびターゲット データベースの指定
### 接続ユーザー情報とパスワードを明記する場合　
 SET SERVER CAPTURE TO DB SAMPLE  id db2admin password db2admimpw ;
 SET SERVER TARGET TO DB TARGETDB id db2admin password db2adminpw ;
```
または
```
### ソースおよびターゲット データベースの指定
### パスワードはASNCLP実行時に入力する場合　
 SET SERVER CAPTURE TO DB SAMPLE  id db2admin ;
 SET SERVER TARGET TO DB TARGETDB id db2admin ;
```
:::

**３．制御表の作成**
作成したASNCLPスクリプト・ファイル```cre.QREP_CTRL.clpin.txt```を実行します。

:::note
・ASNCLPではコマンドで指定した内容からSQL文を生成しますが、その**SQL文を即時実行するか、生成するだけか**を**SET RUN SCRIPTコマンド**で指定します。
上記のasnclpファイルの例では
　**SET RUN SCRIPT LATER ;**
の方を有効としていますので、まずはSQL文のみが生成されます。

・即時実行の場合は、コメント・アウトになっている
　**SET RUN SCRIPT NOW STOP ON SQL ERROR ON;**
の方を有効にします。

まずはLATERで実行し、構文エラーなどがなくSQL文が正常に生成できるか確認し、エラーがなくなったらNOWで実行する手順をお勧めします。
:::

:::note warn
SET RUN SCRIPT NOWの後ろに指定しているSTOP ON SQL ERROR ONは、SQLステートメントの実行中にエラーが発生した場合、その時点より前の SQL ステートメントをロールバックする指定（デフォルト）です。ただし、ソース側データベースへのSQL文の実行が正しく実行されコミットされたあと、ターゲット側のデータベースへのSQL文がエラーになった場合は、ターゲット側のSQL文のみがロールバックされます。コミット済みソース側のSQL文はロールバックされません。
:::

では、最初は **SET RUN SCRIPT LATER が有効、SET RUN SCRIPT NOWの方がコメント・アウトになっている**ことを確認して、asnclpを実行してください。

:::note
ASNCLPのスクリプト・ファイルは
　**asnclp -f ファイル名** 
で実行することができます。
:::

```
asnclp -f  cre.QREP_CTRL.clpin.txt
```

<details><summary>3.制御表作成ASNCLPコマンド SET RUN SCRIPT LATERでの実行例</summary>

```
====
CMD: ### Qレプリケーション用のASNCLPセッションであることを宣言
====
====
CMD: ASNCLP SESSION SET TO Q REPLICATION;
====
====
CMD: ### 生成されたSQL文を保管するファイル
====
====
CMD: SET OUTPUT CAPTURE SCRIPT "cre.QCAP_CTRL.sql.txt";
====
====
CMD: SET OUTPUT TARGET SCRIPT "cre.QAPP_CTRL.sql.txt";

（中略）

ASN1955I  ASNCLP : 次のファイルを使用しています。キャプチャー SQL スクリプトとして "cre.QCAP_CTRL.sql.txt"、コントロール SQL スクリプトとして "replctl.sql"、ターゲット SQL スクリプトとして "cre.QAPP_CTRL.sql.txt"、およびログ・ファイルとして "cre.QREP_CTRL.clpin.log.txt"。

--- ASNCLP Version 11.5 Build date 2022-09-22 21:41:24
ASN1514I  レプリケーション・アクションは、"2023年xx月xx日 (x曜日) 16時36分21秒 JST" に、"1" 個の成功、"0" 個のエラー、お よび "0" 個の警告を伴って終了しました。

ASN1953I  ASNCLP :  コマンドが完了しました。
```
</details>

「###Qキャプチャー用の制御表の作成」と、「###Qアプライの制御表の作成」のあとに、それぞれ<strong>「"1" 個の成功、"0" 個のエラー」</strong>が出力されていれば、構文エラーなどはありません。

では、エラーがないことが確認できたら、次は即時実行にします。
**LATERの方をコメント・アウトし、NOWの方を有効にして**、ファイルを保管します。
```
### SQLファイルの出力のみ（SQLファイルの内容は自分で実行する）
# SET RUN SCRIPT LATER ;

### 即時実行
 SET RUN SCRIPT NOW STOP ON SQL ERROR ON;
```
再度asnclpを実行します。
```
asnclp -f  cre.QREP_CTRL.clpin.txt
```

<details><summary>3.制御表作成ASNCLPコマンド SET RUN SCRIPT NOWでの実行例</summary>

```
（中略）

ASN1956I  ASNCLP : アクション "CREATE CONTROL TABLES" の SQL スクリプト・ファイルを生成しています。

ASN1955I  ASNCLP : 次のファイルを使用しています。キャプチャー SQL スクリプトとして "cre.QCAP_CTRL.sql.txt"、コントロール SQL スクリプトとして "replctl.sql"、ターゲット SQL スクリプトとして "cre.QAPP_CTRL.sql.txt"、およびログ・ファイルとして "cre.QREP_CTRL.clpin.log.txt"。

--- ASNCLP Version 11.5 Build date 2022-09-22 21:41:24

<ClpInfo2Log:: Preparing to run script.>

<ClpInfo2Log:: Now running SQL...>
ASN1514I  レプリケーション・アクションは、"2023年xx月xx日 (x曜日) 16時40分32秒 JST" に、"1" 個の成功、"0" 個のエラー、お よび "0" 個の警告を伴って終了しました。

<ClpInfo2Log:: The SQL command completed successfully.>

ASN1953I  ASNCLP :  コマンドが完了しました。
```
</details>

今度は
「### Qキャプチャー用の制御表の作成」と、「### Qアプライの制御表の作成」のあとに、以下のようにSQL文の実行の準備をして実行しているというメッセージが出ているはずです。
```
<ClpInfo2Log:: Preparing to run script.>
<ClpInfo2Log:: Now running SQL...>
```
そして、どちらも以下のメッセージが出ていれば、SQL文も正常に実行されています。
```
<ClpInfo2Log:: The SQL command completed successfully.>
```


**４．作成された制御表の確認**
実行するコマンドは、以下になります。
当記事で利用しているDb2 V11.5 FP8の場合は、Qキャプチャー用制御表は25表、Qアプライ用制御表は26表がリストされます。

・SAMPLEデータベースに作成したQキャプチャー用の制御表の確認
```
db2 connect to sample
db2 list tables for schema ASN
```
・TARGETDBデータベースに作成したQアプライ用の制御表の確認
```
db2 connect to targetdb
db2 list tables for schema ASN
```
どのような制御表が作成されるかは、先に紹介した
[ASNCLPコマンドを使ってQレプリケーション制御表を作成する - Qiita][asnclp_qiita]
を参考にしてください。
（この記事のLIST TABLESの例はスキーマの指定がASNでないのでQアプライの制御表は24表になっています。）

以上で　**レッスン2.1 ソースおよびターゲットのコントロール表の作成**の作業は終了です。


## :shamrock: <font color="MediumAquaMarine">レッスン 2.2</font> :shamrock: <br>　ソース・データベースをレプリケーション可能にする
**参照元:** [レッスン 2.2: ソース・データベースをレプリケーション可能にする - IBM Documentation][Lesson2.2]

Db2の更新情報はDb2のログ・ファイルに書かれます。そのためレプリケーション・ソースになるデータベースは、ログが上書きされないように保持するか、またはアーカイブして保管する設定にする必要があります。

データベースのログの保管方法は、データベース構成パラメータの **LOGARCHMETH1** で指定します。
ログ・パスにそのまま保持させる場合は**LOGRETAIN**、アーカイブさせる場合は**DISK:とアーカイブ先のファイルシステム**を指定します。
またLOGARCHMETH1を変更した場合は、データベースのオフライン・バックアップが必要になります。

チュートリアルでは、レプリケーション・センターを利用して「データベースをレプリケーション可能にする」という設定で、自動的に既存のデータベース接続を切り、LOGARCHMETH1を変更し、データベースのバックアップを取得し、取得したバックアップ・ファイルを削除できるかのように記載されているのですが、実際は以下のコマンドを自分で実行するように指示があるだけですので、同様の内容をファイルに記載して実行します。

**１．Db2 CLPコマンド・ファイルの作成**

レプリケーション・センターの指示のままではバックアップ・ファイルが残ってしまうので、ここでは空ファイルに書き出す、つまりバックアップ・ファイルは作成しないように変更します。

```db_dummy_bkup.sql```　ファイルを作成し、以下を記載します。
Linux,AIXの場合は、BACKUP先を**NUL**でなく<strong>/dev/null</strong>に変更してください。

```db_dummy_bkup.sql
CONNECT TO SAMPLE;
QUIESCE DATABASE IMMEDIATE FORCE CONNECTIONS;
CONNECT RESET;
CONNECT TO SAMPLE;
UNQUIESCE DATABASE;
CONNECT RESET;
UPDATE DB CFG FOR SAMPLE USING LOGARCHMETH1 LOGRETAIN;
BACKUP DATABASE SAMPLE TO NUL WITHOUT PROMPTING;
```

**２．ログの保管方法変更とダミーバックアップ取得の実行**
作成した```db_dummy_bkup.sql```を実行します。

```
db2 -tvf db_dummy_bkup.sql
```

<details><summary>2. ログの保管方法変更とダミーバックアップ取得 結果例</summary>

```
CONNECT TO SAMPLE

   データベース接続情報

 データベース・サーバー = DB2/NT64 11.5.8.0
 SQL 許可 ID            = DB2ADMIN
 ローカル・データベース別名 = SAMPLE


QUIESCE DATABASE IMMEDIATE FORCE CONNECTIONS
DB20000I  QUIESCE DATABASE コマンドが正常に完了しました。

CONNECT RESET
DB20000I  SQL コマンドが正常に完了しました。

CONNECT TO SAMPLE

   データベース接続情報

 データベース・サーバー = DB2/NT64 11.5.8.0
 SQL 許可 ID            = DB2ADMIN
 ローカル・データベース別名 = SAMPLE


UNQUIESCE DATABASE
DB20000I  UNQUIESCE DATABASE コマンドが正常に完了しました。

CONNECT RESET
DB20000I  SQL コマンドが正常に完了しました。

UPDATE DB CFG FOR SAMPLE USING LOGARCHMETH1 LOGRETAIN
DB20000I  UPDATE DATABASE CONFIGURATION コマンドが正常に完了しました。

BACKUP DATABASE SAMPLE TO NUL WITHOUT PROMPTING

バックアップは成功しました。 このバックアップ・イメージのタイム・スタンプは
2023xxxxxxxxxx です。
```
</details>

**３．LOGARCHMETH1の設定の確認**
ログの保管方法が正しく変更されたか、データベース構成パラメータのLOGARCHMETH1の設定を確認します。

Linux,AIXの場合は、**findstr**でなく**grep**に変更してください。
```
db2 get db cfg for sample | findstr LOGARCHMETH1
```
```
第 1 ログ・アーカイブ・メソッド          (LOGARCHMETH1) = LOGRETAIN
```

これで、SAMPLEデータベースのログの保持方法の変更は完了です。

:::note
ここではレプリケーション・センターの指示に従い、一度データベースをQUIESCEで静止モードにして全てのユーザーの接続を強制的に切断し、その後UNQUIESCEで静止モードを解く方法を利用しましたが、自分一人しかデータベースに接続していない場合は、自分が接続しているセッションを明示的にTERMINATEして終了させるだけでも良いです。
:::

ここまではQレプリケーションの環境を構築する際に、一度実施すればよい作業です。

以降の作業は、レプリケーション対象の表の数やレプリケーションの構成によって、複数回実施する場合もある作業になります。
MQのキューやチャネルも、レプリケーションの構成によって追加で作成が必要になる場合もあります。


**次のステップ　:four_leaf_clover: モジュール 2 :four_leaf_clover:  Q レプリケーションのセットアップ--後半--**
→　[**Qレプリケーション・チュートリアル ASNCLP版（４）**][Qrep_nonGUI.4]


[Qrep_nonGUI.1]: https://qiita.com/Seven_Marine/private/a2e93561e6b8629725ee
[Qrep_nonGUI.2]: https://qiita.com/Seven_Marine/private/31bb30f28d6ed362c785
[Qrep_nonGUI.3]: https://qiita.com/Seven_Marine/private/d86657f0c88e20129515
[Qrep_nonGUI.4]: https://qiita.com/Seven_Marine/private/95c2ffc913b5fdffc642
[Qrep_nonGUI.5]: https://qiita.com/Seven_Marine/private/de33924e47864a24bf97

[QrepTutrial]: https://www.ibm.com/docs/ja/idr/11.4.0?topic=tutorials-q-replication-tutorial
[QrepTut_Intro]: https://www.ibm.com/docs/ja/idr/11.4.0?topic=tutorial-introduction-q-replication
[QrepTut_Module.1]: https://www.ibm.com/docs/ja/idr/11.4.0?topic=tutorial-module-1-setting-up-mq
[QrepTut_Module.2]: https://www.ibm.com/docs/ja/idr/11.4.0?topic=tutorial-module-2-setting-up-q-replication
[QrepTut_Module.3]: https://www.ibm.com/docs/ja/idr/11.4.0?topic=tutorial-module-3-starting-q-replicationting

[Lesson2.1]: https://www.ibm.com/docs/ja/idr/11.4.0?topic=replication-lesson-21-creating-source-target-control-tables
[Lesson2.2]: https://www.ibm.com/docs/ja/idr/11.4.0?topic=replication-lesson-22-enabling-source-database
[Lesson2.3]: https://www.ibm.com/docs/ja/idr/11.4.0?topic=replication-lesson-23-creating-queue-map
[Lesson2.4]: https://www.ibm.com/docs/ja/idr/11.4.0?topic=replication-lesson-24-creating-q-subscription

[asnclp_Qrep]: https://www.ibm.com/docs/ja/idr/11.4.0?topic=program-asnclp-commands-q-replication
[asnclp_qiita]: https://qiita.com/namazu-841/items/3f8a017afca9521447ee