All About ACS: IBM i Access Client Solutionsのデータ転送の注意点

IBM i Access for Windows から ACS にデータ転送を切り替える時の注意点をまとめました。

# ACS のデータ転送でできないこと

Access for Windows でできていたことが ACS でできるわけではありません。

## 無変換の転送

ACS では無変換の転送はできません。
FTP のバイナリー転送など ACS 以外の方法での代替が必要です。

## EOF が付かない

テキストファイルでダウンロードする時、EOF(X'1A') が付きません。

## Excelデータ転送アドイン
Access for Windows では Excel 内部からデータ転送を実行することができました。Java で動く ACS にできる芸当ではありません。
ACSでは転送元・転送先として「アクティブExcelスプレッドシート」が選べます。
これは今開いている Excel を対象とするものです。代替として使えるかもしれません。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/184930/110fe1f6-1652-a38f-1de6-904331e6e294.png)

また、ダウンロードであれば、Excel自体のデータ取得機能も使えます。

ACS の Windows Application Package を導入し、ODBC経由でのMS-Query を使ったもいいでしょう。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/184930/31dc50f6-c644-9c40-5995-778f84809a76.png)

「データベースから」→「IBM DB2 データベースから」という選択肢もあります。この場合、IBM i ポート 446 の DRDAサーバーに接続されます。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/184930/3071e133-c1ec-87fa-2dc8-5760963819fe.png)

ただし、ドライバーとして「IBM」を選択すると、Windows に DB2 CONNECT が必要になります。
「Microsoft」ドライバーを使えば、DB2 CONNECT も ACS Windows Application Package も不要です。クライアント側のサポートは Microsoft 社のサポートになります。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/184930/904bcc60-32d1-352b-95f8-c795a1f6dc6b.png)

## IBM の手順文書 (2019-07-02 追記)

IBM からExcel 転送の手順の文書が、出ています。

ダウンロードはこちらです。
[ACS Data Transfer Download to Excel Spreadsheet]
(http://www-01.ibm.com/support/docview.wss?uid=nas8N1021261)

アップロードはこちらです。こちらには、「アクティブExcelスプレッドシート」からの転送手順も記載されています。
[Transferring Data From Excel using Access Client]Solutions(http://www-01.ibm.com/support/docview.wss?uid=nas8N1021503)

# 文字コードの選択

## Shift_JIS コードに変換したい時は、windows-31j を選択

ACS は Toolbox for Java で DB2 for i と Unicode の変換を行い、Java のコンバーターで Unicode とローカルファイルの変換を行います。Java の Shift_JIS コンバーターは、JIS 第一・第二水準しか含まれません。メーカー拡張文字の変換が必要な場合は、windows-31j を選択します。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/184930/318c64c9-ff48-39f1-9b12-22a40dcb83e2.png)

## UTF-8 の BOM 付き、BOM 無し

どちらも選べますが、場所が離れています。

BOM 付きはリストの先頭にあります。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/184930/42c9ea8d-9095-965c-6ec3-96f70e2b9882.png)

BOM 無しは Unicode 系の最後です。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/184930/b2d0fdae-7dd2-5ca5-5fbe-2effd124f8c5.png)

# タイトルに列見出しの利用が可能

ACS でちょっとうれしいのは、フィールド名以外に、列見出しをタイトルにできることです。

ファイルの詳細で「拡張」をクリックします。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/184930/10159524-ada2-03eb-12fd-8c09c9db166a.png)

「列見出し」を選択します。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/184930/e664a175-fc52-df92-5e4d-f9023f2305b8.png)

表示されました。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/184930/9992acb1-48a0-b66f-d725-3b79e1380664.png)


# Excel 転送

Excel 転送のやり方として、IBMのサポートページにある英語の文書はこちらです。

[ACS Data Transfer Download to Excel Spreadsheet](http://www-01.ibm.com/support/docview.wss?uid=nas8N1021261)

## Excel に転送するときは、xls ではなく xlsx を使う

ACS では Excel と扱い場合に [Apache POI](https://poi.apache.org/) を利用しています。
Apache POI では、xls を操作する場合、スプレッドシート全体の情報をすべてメモリーに展開します。
データ量が多い場合は Out of Memory が発生して 転送が失敗します。-Xmx でヒープの最大値を増やすこともできますが、限界があります。

Apache POI の xlsx 操作では、すべてをメモリーに展開することは、ありません。
どうしても、xls が必要な場合は、xlsx でダウンロードして、xls に変換することができます。

詳細は、こちらをご覧ください。

[IBM i Access Client Solutions Data Transfer to XLS File Format](https://www-01.ibm.com/support/docview.wss?uid=ibm10879941)

## シートの名前

デフォルトでは「スキーマ.テーブル>シートn」のような名前にななります。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/184930/ee8a1ebd-646e-895e-3854-d0bf75e4612e.png)

これを変更する方法は、下記のように GettingStarted_ja.html にガイドされています。ただし「シート1」の部分は除去できません。

> **9.8.3 データ転送シート名**
>
> ダウンロード時に、シート名が生成されます。シート名は IBM i ソース・ライブラリーとファイルの名前を基にして「>Sheet#」が付加されます。ここで、 # は、適切なシート番号に置き換えられます。例:
    qiws.qcustcdt>Sheet1

> シート名のライブラリーとファイルの部分を指定変更するには、以下のプロパティーを指定します。
    com.ibm.iaccess.dataxfer.SheetId=your_string
>これにより、以下のように生成されます。
    your_string>Sheet1 

# データの切り捨て

データをアップロードする時に、宛先のカラムに対して文字列が長すぎる場合や、数値が大きすぎる/小さすぎる場合、デフォルトではデータ転送は失敗します。

切り捨ててデータ転送を成功させるオプションが、GettingStarted_ja.html にガイドされています。

> **9.8.2 データ転送での文字切り捨ておよび数値オーバーフローのサポート**
>
>データ転送のアップロード要求時に、文字フィールドまたは数値フィールドが定義済みフィールド・サイズを超える場合、アップロード要求は終了します。
>
>文字フィールドの末尾からの切り捨てを有効にするには、以下のプロパティーを AcsConfig.properties ファイルに設定します。
    com.ibm.iaccess.dataxfer.jdbc.AllowCharacterTruncation=true

>指定された数値フィールドが定義済み境界を超える場合に、数値フィールドを正または負の最大値に設定できるようにするには、以下のプロパティーを AcsConfig.properties ファイルに設定します。
>    >com.ibm.iaccess.dataxfer.jdbc.AllowNumericOverflow=true
>
>これらのプロパティーを true に設定すると、切り捨てまたはオーバーフローが発生したことを表示せずに、アップロード要求が続行されます。文字フィールドは末尾で切り捨てられます。数値フィールドは、オーバーフローの場合は最大値に、アンダーフローの場合は最小値に設定されます。
>
>あるいは、他の java プロパティーと同様に、上記のプロパティーをコマンド行から以下のように設定できます。
>    >-Dcom.ibm.iaccess.dataxfer.jdbc.AllowCharacterTruncation=true
>    >-Dcom.ibm.iaccess.dataxfer.jdbc.AllowNumericOverflow=true 

~~ただし、文字列を切り捨てる時、強制的に切り捨てるため、OE/OFの整合性が考慮されません。
機能拡張のRFEが出ています。みんなで Vote して IBM に必要性を訴えましょう。~~

 http://www.ibm.com/developerworks/rfe/execute?use_case=viewRfe&CR_ID=123954

2020-02-26 追記 **1.1.8.2で RFEに対応したそうです。**

>As of version 1.1.8.2 released May 2019, setting the property:
com.ibm.iaccess.dataxfer.jdbc.AllowCharacterTruncation=true
...should preserve the shift characters during an upload.
>
>Please retry your scenario with version 1.1.8.2 or later.   Let us know if this meets the requirement.

# 拡張子を付けないダウンロード

ダウンロードファイルに拡張子が指定されていないと、ACSはファイル形式をもとに、自動的に拡張子を付けます。
拡張子を付けたくない場合は、ファイル名の最後に「.」(ピリオド)を付けてください。

# 拡張子がファイルタイプと合わない場合の警告を出さない(2019-07-02 追記)

形式で csv を選び、拡張子を .txt にするなど、拡張子がファイルタイプと合わない場合、ACSは下記の警告を出します。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/184930/3bc0219f-6440-71a5-4a49-7e3feb4891ff.png)

警告を出さない方法は、下記に文書化されています。

[Access Client Solutions Data Transfer File Extension Warning](https://www-01.ibm.com/support/docview.wss?uid=nas8N1022563)

実行時に指定する方法も紹介されていますが、AcsConfig.properties に「com.ibm.iaccess.dataxfer.ignoreAmbiguousDownloadExt=true」を記述するほうが、単純でしょう。

# データ転送要求ファイルのマイグレーション

既存の転送要求のマイグレーションは、データ転送メインメニューから 「アクション」->「データ転送マイグレーション」で行います。
GettingStarted_ja.html にガイドされています。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/184930/65692488-8194-099f-48c1-b823f232532f.png)

> **9.6.3 保管されたデータ転送要求ファイルのマイグレーション**
>
>IBM i Access Client Solutions のデータ転送には、IBM i Access for Windows によって生成された保管済みデータ転送要求ファイルを変換するためのウィザードがあります。
>
>以下のファイル・タイプは、IBM i Access for Windows から変換できるものです。
>
>   .dtf - IBM i からのデータ転送
>   .dtt - IBM i へのデータ転送
>
>これらのファイルは以下のファイルに変換されます。
>
>   .dtfx - IBM i からのデータ転送
>   .dttx - IBM i へのデータ転送
>
>データ転送マイグレーション・ウィザードは .fdf ファイルをマイグレーションしません。 IBM i Access Client Solutions で必要な新規ファイル・タイプは、タイプ .fdfx であり、 ダウンロード時に生成するか、ファイル作成ウィザードを使用して生成できます。
>
>データ転送マイグレーション・ウィザードは、データ転送メインメニューで 「アクション」->「データ転送マイグレーション」と選択すると使用可能です。 

# データ転送の自動化

/PLUGIN の指定でデータ転送を自動化することができます。
既存の転送要求を使う場合は、このようになります。

* ダウンロード: /PLUGIN=download [/userid=<userid>] \<file.dtfx> 
* アップロード: /PLUGIN=upload   [/userid=<userid>] \<file.dttx> 

ユニークなのは、cldownload です。
転送共有ファイルの代わりに、ダウンロードするファイル名やSQL文を直接指定するので、実行時に柔軟な指定が可能です。

> **9.1.17 CLDownload**
>
>/PLUGIN=cldownload /system=\<system>
>                          [/userid=<userid>]
>                          {/hostfile=\<library/filename> | >/sql="statement"}
>                          {/clientfile=\<path>\<filename>.\<extension> | /display}
>
>    /userid     - ターゲット・システムに接続する際に使用するユーザー ID
>    /hostfile   - ダウンロード用の IBM i システム上のソース・ライブラリーおよびファイル
>                  例: /hostfile=QIWS/QCUSTCDT
>    /sql        - SQL ステートメントを指定します
>                  例: /sql="select CUSNUM,LSTNAM,INIT,ZIPCOD from QIWS/QCUSTCDT"
>    /clientfile - ダウンロード用のターゲット・ファイルの場所。
>                  このファイルのフォーマットは、指定された拡張子 (.csv、.ods、.xlsx、.xlsx 
>                  など) によって決定されます。
>                  ファイル拡張子が指定されていない場合、またはサポートされないタイプ
>                  である場合、データは .csv ファイルとしてフォーマットされます。
>     /display    - 出力を端末に書き出します

# 自動化したデータ転送で、ロゴマークを表示しない(2019-07-02 追記)

上記の/PLUGINの指定でデータ転送を自動化する時に、下記のロゴマークが表示されるようになりました。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/184930/f4630fc5-c611-b2f2-eae6-880fad9b677f.png)

表示しないようにするには「-Djava.awt.headless=true」を実行時に指定してください。

exe 起動の場合は、このように指定します。
```
C:\ACS>acslaunch_win-64.exe -Djava.awt.headless=true /PLUGIN=download mytfr.dtfx
```

java 起動の場合は、このように指定します。
```
C:\ACS>java -Djava.awt.headless=true -jar acsbundle.jar /PLUGIN=download mytfr.dtfx
```

# テキスト転送でパック10進数に対する文字数が Access for Windows と違う (2019-07-02 追加)

下記に情報があります。

[ACS Data Transfer of Packed Decimal Data](http://www-01.ibm.com/support/docview.wss?uid=nas8N1021775)

Access for Windows が正しくなかったそうです。ACS で修正されました。Access for Windows と同じ結果を得るために、フィールド選択をして、1バイドのブランク(' ')を、フィールドに追加する方法が紹介されています。

***
2019-06-25 作成
2019-06-26 テキストダウンロードでEOFが付かないことを追記
2019-07-02 
ｰ Excel 転送での IBM の手順文書の項を追記
- 拡張子がファイルタイプと合わない場合の警告を出さない項を追記
ｰ 自動化したデータ転送で、ロゴマークを表示しない項を追記
- テキスト転送でパック10進数に対する文字数が Access for Windows と違う項を追記
- 2020-02-26 データ転送での文字切り捨てで1.1.8.2からシフト文字整合性に対応したことを追記

***
「All About ACS」では IBM i に対する新しいクライアント「IBM i Access Client Solutions」の情報をいろいろ提供していきます。
[記事一覧はこちら](http://qiita.com/6onoda/items/2dc925586d8d3b8644f2)で確認いたけます。

許可の無い転載を禁じます。
この記事は筆者の個人的な責任で無保証で提供しています。
当記事に関してIBMやビジネスパートナーに問い合わせることは、固くお断りします。
***