VS Code - z/OS接続構成 (Zowe CLI V2編)

# はじめに
VS CodeのExtensionを使用すると、VS Codeからz/OSに接続してz/OS上のリソースを操作することができます。例えば、MVSデータセット/USS上のファイルを参照/編集したり、JCLのサブミットやJOBLOG参照などをVS Codeから行えるようになります。
この辺りは「[VSCodeを使用したメインフレーム・アプリケーション開発](https://qiita.com/tomotagwork/items/085b91098fce3aabaeaf)」という一連の記事に記載しましたが、接続構成については変更されているので改めてここに記載します。

# 参考

[Installing Zowe CLI](https://docs.zowe.org/stable/user-guide/cli-installcli/#install-zowe-cli-from-npm)
[Visual Studio Code (VS Code) Extension for Zowe](https://docs.zowe.org/stable/user-guide/ze-install)
[Zowe Explorer profiles](https://docs.zowe.org/stable/user-guide/ze-profiles)
[Using Zowe CLI - Team Configuration](https://docs.zowe.org/stable/user-guide/cli-using-using-team-profiles)
[How Zowe CLI uses configurations](https://docs.zowe.org/stable/user-guide/cli-using-understand-profiles-configs/)
[IBM Z Open Editor - Creating a configuration profile in Zowe Explorer v2.0.0](https://ibm.github.io/zopeneditor-about/Docs/creating_team_profiles.html#initializing-the-configuration-file)
[Configure your applications with ZAPP files](https://ibm.github.io/zopeneditor-about/Docs/zapp.html#zapp-use-cases)
[Setting property groups](https://ibm.github.io/zopeneditor-about/Docs/setting_propertygroup.html)

# 構成イメージ

VSCodeからz/OSに接続して操作を行う場合、z/OS側にもコンポーネントを導入してセットアップする必要があります。z/OS側のコンポーネントとしては2種類あり、基本的にはどちらかをセットアップすればよいです。

(1) z/OSMF(z/OS Management Facility): z/OSが提供する機能の1つで、z/OS管理に関する様々機能を提供しており、ブラウザベースのUIや管理用のAPIなどが提供されます。z/OS機能の1部なので追加コスト無しで利用できます。
(2) RSE API(Remote System Explorer API): z/OS Explorerのホスト・コンポーネントの1つとして提供されます。基本的に無償で利用できますが、IDzなどの有償製品と合わせて利用する場合でなければ保証されません。
参考: [Introducing IBM Remote System Explorer API](https://community.ibm.com/community/user/ibmz-and-linuxone/blogs/blog-entry1/2020/06/12/introducing-ibm-remote-system-explorer-api)

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/132331/afad881b-162a-c94c-c507-3ad3c28bca95.png)

VSCodeからz/OSに接続する際は、内部的にZowe CLIというコンポーネントを使ってz/OSとの通信が行われます。
(1)の場合は接続先はz/OSMFとなるので、Zowe CLIではz/OSMFとの接続構成を行うことになります。(2)の場合は接続先がRSE APIとなり、Zowe CLIのプラグインであるRSE API plug-inを追加でインストール/構成する必要があります。
この記事では、(1)のz/OSMFを使用した接続を前提として話を進めていきます(RSE APIは使用しない)。

# 環境情報

以下はインストール済みの想定です。

## PC側
Windows 11

```
c:\>node -v
v16.16.0

c:\>npm -v
8.15.1

c:\>npm list -g
C:\Users\A00527JP6\AppData\Roaming\npm
+-- @zowe/cli@7.13.0
`-- npm@8.15.1


c:\>zowe --version
7.13.0
```

VS Code v1.87.0
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/132331/03121018-8b23-326a-90fb-a0d34c115a6f.png)

VS Code Extension
 - Zowe Explorer v2.14.1
 - IBM Z Open Editor v3.4.0

## z/OS側

z/OS V2.5
z/OSMF構成済み

# 接続構成

VS CodeからZowe Explorer Extensionを使ってz/OSに接続する際は、内部的にZowe CLIの機能が使われます。z/OSとの接続用の構成はzowe profileと呼ばれるもので管理されますが、Zowe CLI V2からzowe profileの管理方法が変わりました。ここではZowe CLI V2ベースの構成方法を記載します。
参考: Zowe CLI V1ベースの接続構成 => [Zowe CLI接続構成](https://qiita.com/tomotagwork/items/cfeec0ccab50d72a48e2#zowe-cli%E6%8E%A5%E7%B6%9A%E6%A7%8B%E6%88%90)

## 構成ファイル概要

z/OSへの接続情報はJSON形式の構成ファイルで管理されるようになりました。構成ファイルは主に以下の2種類があります。
- **プロジェクト構成ファイル**(zowe.config.user.json): プロジェクトごとにプロファイルを管理。プロジェクトのディレクトリのトップに配置される。
- **グローバル構成ファイル**(zowe.config.json): 使用しているユーザー全般で有効なプロファイルを管理。`<ユーザーのホーム>\.zowe\`以下に配置される。

## VS Code上での構成ファイル作成方法

VS Codeからの構成ファイルの作成方法を試してみます。

VS Code上でプロジェクトを作成している状態で、Zowe Explorerのview上のDATA SETSの横の「+」アイコン(Add Profile to Data Sets View)を選択します。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/132331/9cb9698f-d4d0-1abe-e9a3-362c10f0dfc8.png)

プルダウンメニューから「Create a New Team Configuration File」を選択します。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/132331/429eee8b-10e1-d786-513f-8758e23e6853.png)

作成したいプロファイルを選択します。ここではProject構成ファイルを作成するために、「Project: in the current working directory」を選択します。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/132331/74976ff8-0c6f-52a1-f369-01b0d37a01d3.png)

プロジェクトのトップのディレクトリに zowe.config.user.jsonという構成ファイルの雛形が作成されます。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/132331/ab51cef8-4501-5896-13e3-8588f1994e6c.png)

<details><summary><font color="blue">zowe.config.user.json雛形</font></summary><div>

```json:zowe.config.user.json
{
    "$schema": "./zowe.schema.json",
    "profiles": {
        "zosmf": {
            "type": "zosmf",
            "properties": {
                "port": 443
            },
            "secure": []
        },
        "tso": {
            "type": "tso",
            "properties": {
                "account": "",
                "codePage": "1047",
                "logonProcedure": "IZUFPROC"
            },
            "secure": []
        },
        "ssh": {
            "type": "ssh",
            "properties": {
                "port": 22
            },
            "secure": []
        },
        "rse": {
            "type": "rse",
            "properties": {
                "port": 6800,
                "basePath": "rseapi",
                "protocol": "https"
            },
            "secure": []
        },
        "base": {
            "type": "base",
            "properties": {
                "host": "",
                "rejectUnauthorized": true
            },
            "secure": [
                "user",
                "password"
            ]
        }
    },
    "defaults": {
        "zosmf": "zosmf",
        "tso": "tso",
        "ssh": "ssh",
        "rse": "rse",
        "base": "base"
    },
    "autoStore": true
}
```

</div></details>

※VS Codeのワークスペースを作成し、複数のプロジェクトを追加している場合、そのワークスペースの最初のプロジェクトに含まれるzowe.config.user.jsonが有効になります。

※Globalを選択した場合は、`<ユーザーのホーム>\.zowe\zowe.config.json`が作成されます。

## 構成ファイルのカスタマイズ

以下の辺りの記述を参考に、構成ファイルをカスタマイズします。

参考: [Team configuration for team leaders](https://docs.zowe.org/stable/user-guide/cli-using-team-configuration-team-leaders)

<details><summary><font color="blue">zowe.config.user.json設定例</font></summary><div>

```json:zowe.config.user.json
{
    "$schema": "./zowe.schema.json",
    "profiles": {
        "eplex1": {
            "properties": {
                "host": "eplex1"
            },
            "profiles": {
                "zosmf": {
                    "type": "zosmf",
                    "properties": {
                        "port": 10443,
                        "encoding": "IBM-1399"
                    }
                },
                "tso": {
                    "type": "tso",
                    "properties": {
                        "account": "ACCT#",
                        "codePage": "1047",
                        "logonProcedure": "IZUFPROC"
                    }
                },
                "ssh": {
                    "type": "ssh",
                    "properties": {
                        "port": 22
                    }
                }
            },
            "secure": [
                "user",
                "password"
            ]
        },
        "isecloud_zdt01": {
            "properties": {
                "host": "zdt01"
            },
            "profiles": {
                "zosmf": {
                    "type": "zosmf",
                    "properties": {
                        "port": 10443
                    }
                }
            },
            "secure": [
                "user",
                "password"
            ]
        },
        "isecloud_wazi01": {
            "properties": {
                "host": "wazi01"
            },
            "profiles": {
                "zosmf": {
                    "type": "zosmf",
                    "properties": {
                        "port": 10443
                    }
                },
                "ssh": {
                    "type": "ssh",
                    "properties": {
                        "port": 22,
                        "privateKey": "C:\\Users\\A00527JP6\\.ssh\\ISECloud2023\\id_rsa_wazi"
                    }
                }
            },
            "secure": [
                "user",
                "password"
            ]
        },
        "base": {
            "type": "base",
            "properties": {
                "rejectUnauthorized": false
            }
        }
    },
    "defaults": {
        "zosmf": "eplex1.zosmf",
        "tso": "eplex1.tso",
        "ssh": "eplex1.ssh",
        "base": "base"
    },
    "autoStore": true
}
```

</div></details>

上の例では複数のz/OSに対する接続構成を作成しています。1つめのz/OSについてはz/OSMF用のプロファイル、TSO用のプロファイル、SSH用のプロファイルと3つのプロトコルでの接続プロファイルを作成しています(データセットの編集やJCLサブミットなど基本操作はz/OSMF用のプロファイルだけあればOKです)。

## 接続プロファイルの追加

上で作成したプロファイルをZowe Explorerのビューに追加することで、そのプロファイルに示すz/OSへの接続が行われて各種リソースの操作が行えるようになります。

Zowe Explorerのview上のDATA SETSの横の「+」アイコン(Add Profile to Data Sets View)を選択します。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/132331/9cb9698f-d4d0-1abe-e9a3-362c10f0dfc8.png)

プルダウンメニューに、上で追加したプロファイルがリストされますので追加したいプロファイルを選択します。ここではeplex1.zosmf(eplex1というz/OSに対するz/OSMFプロファイル)を選択します。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/132331/598c1816-d15e-8546-b657-1e22d287e59c.png)

DATA SET以下にeplex1.zosmfが追加され、Datasetに対する操作ができるようになりました。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/132331/0423a9e1-fff3-cc6f-9a8f-1eb9a3518325.png)

# データセット操作例

## データセット検索

追加したプロファイルの右横の虫メガネアイコンをクリックします。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/132331/c626cf79-a0d2-0bf7-1655-f3b01f8936de.png)

最初の接続のタイミングで、TSOユーザーID/パスワードを入力する必要があります。
指示に従って、接続に使用するユーザーIDを入力します。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/132331/d0da63fe-b5c1-a897-0b0b-47e19a831d28.png)

次にパスワードを入力します。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/132331/2865774b-bb29-fedc-8bae-bd86ff06b09d.png)

※ここではz/OSMF経由での接続を行う想定ですので、z/OSMF提供のAPIが発行できる権限を持ったユーザーを使用する必要があります。

参照したいデータセットのフィルターを指定します。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/132331/532eed55-ad1a-f7ae-ad63-4126faf22d9f.png)

Enter
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/132331/8281890f-8dc7-ed72-63f9-2f8481253414.png)

指定したフィルターでデータセットが参照できるので、メンバー(COBOLのソースなど)を開いて編集操作などが行えます。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/132331/6e3f5737-3be0-f30e-0ebc-a325e83cf28e.png)


同様のイメージでUSSファイルやJOBLOGなどの操作が可能です。


# ユーザー/パスワードの管理

一度ユーザー/パスワードを指定して接続するとその情報は内部的に保持されるので2回目以降はユーザー/パスワードを指定しなくてもアクセス可能です。
接続するユーザーを変更したい場合は、追加したプロファイルを右クリック - Update Credentials を選択すると変更可能です。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/132331/5b1ff017-bfc3-5846-ca4a-abc7dc0248a6.png)

## 補足

上の通り、ユーザー/パスワードの情報は内部的に保持/管理されます。これは、上の構成ファイル(zowe.config.user.json)の例でいうと、`"autoStore": true` という設定をしているためです。

参考: [Configure Zowe CLI on operating systems where the Secure Credential Store is not available](https://docs.zowe.org/stable/user-guide/cli-configure-cli-on-os-where-scs-unavailable)
>By default, Zowe CLI attempts to store sensitive information and credentials in the operating system’s credential manager. 

具体的な情報を保持する場所としては、OS提供のcredential managerが使用されます。Windowsでは「資格情報マネージャー」と呼ばれる機能で管理されます。
パスワード情報を設定してautoSaveされた後、コントロール・パネルからWindowsの資格情報マネージャーを開くと、Windows資格情報 - 汎用資格情報の欄に「Zowe/secure_config_props」という資格情報が追加されているのが確認できます。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/132331/a867f72d-eb5c-e5bd-bfa0-2ac616ada489.png)

ユーザー/パスワード情報はここでまとめて管理されているようです。



# Tips

## z/OSMF セキュリティーの管理

z/OSMF経由で接続する場合z/OSMFのREST APIが内部的に使用されますので、接続に使用するユーザーがz/OSMFに関する適切な権限を保持している必要があります。
(例えばz/OSMF管理者権限を付与するのであれば使用するユーザーをIZUADMINグループにCONNECTするなど)
参考: [z/OSMF のセキュリティー構造](https://www.ibm.com/docs/ja/zos/2.5.0?topic=guide-security-structures-zosmf)

## リージョン・サイズ

VS Codeからz/OSMF経由でz/OS上のリソースにアクセスした際に[IKJ56423I](https://www.ibm.com/docs/ja/zos/2.5.0?topic=ikj-ikj56423i)のエラーが発生することがありますが、この場合ユーザーに割り当てられるリージョンサイズが小さい可能性があります。ユーザー・プロファイルのTSOセグメントの設定を見直すことをおすすめします。(256MB程度は必要)

TSOコマンド例: `ALTUSER USER01 TSO(SIZE(300000) MAXSIZE(0))`

参考:
[The TSO segment in user profiles](https://www.ibm.com/docs/en/zos/2.5.0?topic=profiles-tso-segment-in-user)
[ALTUSER (Alter user profile)](https://www.ibm.com/docs/en/zos/2.5.0?topic=syntax-altuser-alter-user-profile)

## エラー情報の調査
z/OSMF経由で接続している場合、各種操作を行うと内部的にはz/OSMF提供のREST APIが使用されることになります。何か問題が発生してエラーが表示される場合、z/OSMFのREST APIでエラーが発生することがよくあります。その場合、Retrun CodeやReason Codeなどが返されることになりますが、まず初動調査としてはそのエラーの内容を確認する必要があります。

例えば、データセットやUSSファイルアクセス時にエラーになった場合は以下のリンクからエラーの意味を探ります。
参考: [z/OS V2.5 - Using the z/OSMF REST services - z/OS dataset and file REST interface - Error reporting categories](https://www.ibm.com/docs/en/zos/2.5.0?topic=interface-error-reporting-categories)