はじめに：VSCodeでz/OSを操作する

z/OS（メインフレーム）の操作といえば、昔ながらの3270エミュレータを思い浮かべる方が多いのではないでしょうか。黒い画面と緑の文字、独特のキー操作など…慣れれば効率的に操作できますが、使いづらさを感じることもあるかもしれません。特に、若い世代にとっては、使いづらさの壁がメインフレーム開発への参入障壁になっている可能性も否めません。

そこで登場するのが、VSCodeを使ったz/OSの操作です。Zowe ExplorerプラグインとZowe CLIコマンドラインツールを組み合わせることで、VSCodeからz/OSのリソースにアクセスできるようになります。ファイル編集、ジョブ実行、データセット操作などがVSCode上で行えるため、開発効率の向上、学習コストの削減に繋がります。

VSCodeとz/OSを連携させるには、z/OS側にz/OS Management Facility (z/OSMF) が必要です。z/OSMFは、z/OSの様々な機能をREST APIとして公開するミドルウェアで、ZoweはこのAPIを利用してz/OSと通信します。

実際にVSCodeとz/OSの連携環境を構築してみたところ、「Zoweとz/OSMFはどのように連携しているのか？ z/OSMFはAPIリクエストをどのように処理するのか？ z/OSMFにはどのような定義が必要なのか？」という疑問が浮かびました。

まずは、z/OSMF固有ではなく、一般的なサーバー内部に必要な定義や処理フローについて調査してまとめました。
詳細は以下の記事をご覧ください。
APIサーバーの内部動作：リクエストからレスポンスまでの処理の流れ

本記事では、z/OSMFを経由したVSCodeとz/OSを連携について、APIリクエストが発行されてからレスポンスが返されるまでの流れ、そしてz/OSMFに存在する定義について詳しく見ていきます。

z/OSMFの役割

z/OSMFの役割について解説していきます。
z/OSの操作はISPFなどの専用インターフェースを介して行われ、他システムとの連携には高いハードルがありました。z/OSMFはz/OSの機能をREST APIとして公開することでこれらを解決し、様々なツールがz/OSにアクセスできるようになりました。

その代表例が Zowe です。Zowe Explorer と Zowe CLI は、z/OSMF の API を利用して z/OS のリソースへのアクセスと操作を実現します。Zowe Explorer を使用すると、VSCode 上で、クリック操作による z/OS の操作が可能になります。一方、Zowe CLI を使用すると、Node.js のコマンドプロンプトからコマンドを実行することで z/OS を操作できます。

z/OSMFのAPIは多種多様で、データセット操作、ジョブ実行、システム情報取得などz/OSの主要機能をAPI経由で利用できます。
概念的に図示すると以下のようなイメージになるかと思います。

APIリクエスト処理の流れ：サーバー内部の動き

前回の記事でも記載しましたが、APIサーバーはクライアントからのリクエストを受け取ると、内部で様々な処理を行います。順を追って解説します。

リクエストの受信: クライアントからのHTTPリクエストをAPIサーバーが受信。サーバーは特定ポートでリクエストを待ち受け、接続を確立する
ルーティング: 受信したリクエストはURLに基づき適切な処理へルーティングされる。例えば、/datasets ならデータセット一覧取得処理、/jobs ならジョブ操作処理へと振り分けられる
認証認可: APIによってはアクセス制限があり、リクエストに含まれる認証情報（APIキーやアクセストークンなど）を検証し、アクセス権限を持つクライアントのみ処理を行う
ビジネスロジックの実行: 認証認可後、リクエストに対応するビジネスロジック（APIの具体的な機能を実装した処理）が実行される。データセット一覧取得APIならz/OSのデータセット一覧を取得する処理、ジョブ実行APIならz/OSにジョブを実行する処理が実行される
レスポンスの生成: ビジネスロジックの実行結果に基づき、HTTPレスポンス（ステータスコード、ヘッダー、ボディ）が生成される。ボディにはリクエストされたデータやエラーメッセージなどが含まれる
レスポンスの送信: 生成されたHTTPレスポンスはクライアントに送信される。クライアントはレスポンスを受信し、データを取得したり、ステータスコードを確認してエラー処理などを行う

z/OSMFのAPI連携

この章では、z/OSMFを経由したVSCodeとz/OSを連携におけるAPI リクエスト処理を解説します。 Zowe Explorer と Zowe CLI の両ツールを使用した場合の、具体的な処理の流れと例を示します。

0. 共通のポイント

Zowe Explorer (VS Code 拡張) や Zowe CLI は、z/OS と直接対話するのではなく、z/OSMF が提供する REST API を利用して z/OS の機能にアクセスする
z/OSMF は、API リクエストを受け取ると、z/OS の対応するサービスを呼び出し、結果を返す
セキュリティ確保のため、z/OSMF への API リクエストには認証情報が必要

1. Zowe Explorer (VS Code 拡張) の場合

例えば、VS Code 上で Zowe Explorer を使ってデータセットを閲覧する場合、以下の流れで処理が行われます。

操作: ユーザーが Zowe Explorer でデータセットの閲覧操作を行う
API リクエスト生成: Zowe Explorer は、この操作に対応する API リクエストを生成する
リクエスト送信: Zowe Explorer は生成した API リクエストを z/OSMF に送信
z/OSMF による処理: z/OSMF はリクエストを受け取り、対応する z/OS サービスを呼び出す
z/OS からの応答: z/OS は処理結果を z/OSMF に返す
レスポンス返却: z/OSMF は結果を Zowe Explorer に返す
表示: Zowe Explorer は結果を VS Code 上に表示する

2. Zowe CLI の場合

例えば、zowe zos-files list data-set "SAMPLE.DATASET.NO*" コマンドを実行する場合、以下の流れで処理が行われます。

コマンド入力: ユーザーが上記のコマンドを入力する
API リクエスト生成: Zowe CLI はコマンドを解析し、対応する API リクエストを生成する
リクエスト送信: Zowe CLI は生成した API リクエストを z/OSMF に送信
z/OSMF による処理: z/OSMF はリクエストを受け取り、対応する z/OS サービスを呼び出す
z/OS からの応答: z/OS は処理結果を z/OSMF に返す
レスポンス返却: z/OSMF は結果を Zowe CLI に返す
出力: Zowe CLI は結果をコマンドプロンプトに出力

3. 具体的な例

API リクエスト

上記の zowe zos-files list data-set "SAMPLE.DATASET.NO*" コマンドは、内部で以下のような HTTP リクエストに変換されて z/OSMF に送信されると推測されます。

curl -X GET \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <access_token>' \
'https://<IPaddress>:<Port>/zosmf/restfiles/ds?dslevel=SAMPLE.DATASET.NO*'

-X GET: GET メソッドを指定
--header 'Content-Type: application/json': リクエストボディのデータ形式を JSON と指定
--header 'Authorization: Bearer <access_token>': 認証ヘッダー。<access_token> には、z/OSMF へのアクセスに必要な認証トークンが入る
'https://<IPaddress>:<Port>/zosmf/restfiles/ds?dslevel=SAMPLE.DATASET.NO*': API エンドポイントとリクエストパラメータを指定

z/OSMF 内部の処理

z/OSMF は、受信したリクエストを解析し、内部のルーティング定義に基づいて対応する z/OS モジュールにリクエストを転送します。このルーティング定義は、API のエンドポイントと z/OS モジュールのマッピングを規定するものです。例えば、データセット一覧取得のリクエストの場合、IZUGLSDS モジュールがそのビジネスロジックを担っていると推測されます。このモジュールは、リクエストに含まれる dslevel パラメータの値 (データセット名のパターン) を受け取り、z/OS 上で該当するデータセットの検索コマンドを実行すると考えられます。（IZUGLSDS モジュールの詳細な動作は IBM の非公開情報であるため、推測に基づく記述となります。）

ルーティング定義の例:

{
  "servlet-name": "ListDatasets", // z/OSMF 内で使用する識別名
  "url-pattern": "(/ds)$",       // API のエンドポイントのパス
  "method": "GET",                // サポートする HTTP メソッド
  "module": "IZUGLSDS"            // 呼び出す z/OS モジュール名 (ビジネスロジックの実装)
}

この例では、/ds というエンドポイントへの GET リクエストが IZUGLSDS という z/OS モジュールにルーティングされます。 z/OSMF は、この定義に基づいてリクエストを適切なモジュールに転送し、そこでビジネスロジックが実行されます。 IZUGLSDSモジュールは、dslevel パラメータの値に基づいてデータセットを検索し、その結果を z/OSMF に返します。

z/OSMF からのレスポンスの例:

  "items": [
    { "dsname": "SAMPLE.DATASET.NO1" },
    { "dsname": "SAMPLE.DATASET.NO2" },
    { "dsname": "SAMPLE.DATASET.NO3" }
  ],
  "returnedRows": 3
}

概念図

概念的に図示すると以下のようなイメージになるかと思います。

VSCode と z/OS の連携において、z/OSMF は API リクエストを処理する役割を担います。 z/OSMF は、リクエストされた API のエンドポイントに基づいて、定義されたルーティングに従い、対応する z/OS モジュール(ビジネスロジック) を呼び出します。これにより、z/OS の様々な機能を API 経由で利用できるようになります。

まとめ：VSCode で z/OS を操作する際の z/OSMF の役割と連携の仕組み

この記事では、VSCode と z/OS を連携させる際の z/OSMF の役割と、API リクエスト処理の流れについて解説しました。この連携において、z/OSMF は z/OS の機能を REST API として公開するミドルウェアとして重要な役割を果たします。
VSCode 上での操作は、Zowe によって API リクエストに変換され、z/OSMF に送信されます。 z/OSMF は以下の手順でこのリクエストを処理します。

リクエスト受信: z/OSMF は Zowe から API リクエストを受信
ルーティング: リクエストに含まれるエンドポイントに基づいて、内部のルーティング定義を参照し、対応する z/OS モジュールを特定
モジュール実行 (ビジネスロジック): 特定された z/OS モジュールにリクエストのパラメータを渡し、実行を依頼。例えば、データセット一覧取得のリクエストでは、IZUGLSDS モジュールが dslevel パラメータの値に基づいてz/OS上でデータセットを検索する
結果返却: z/OS モジュールからの処理結果を z/OSMF が受け取り、JSON 形式等に変換して Zowe に返送
表示: Zowe は受信した結果を VSCode 上に表示

実際に VSCode と z/OS の連携環境を構築する中で、「Zowe と z/OSMF はどのように連携しているのか？ z/OSMF は API リクエストをどのように処理するのか？ z/OSMF にはどのような定義が必要なのか？」という疑問が浮かびました。今回の調査を通して、これらの疑問に対する答えが得られました。

Q1: Zowe と z/OSMF はどのように連携しているのか？
A1: Zowe CLI や Zowe Explorer はユーザー操作を API リクエストに変換し、z/OSMF に送信。z/OSMF は REST API を用いて z/OS のサービスを呼び出し、結果を Zowe に返す
Q2: z/OSMF は API リクエストをどのように処理するのか？
A2: z/OSMF はルーティング定義に基づき API リクエストを処理する。リクエストのエンドポイントと HTTP メソッドを元に、対応する z/OS モジュールを特定し、パラメータを渡して実行を依頼。モジュールからの処理結果を JSON 形式などでクライアントに返送。
Q3: z/OSMF にはどのような定義が必要なのか？
A3: z/OSMF には API エンドポイントと z/OS モジュールの対応関係を定義する「ルーティング定義」が必要。※API アクセス制御を行う「セキュリティー定義」も必要ですが、これについては別の記事で詳しく解説します

z/OSMF を利用することで、VSCode から z/OS のリソースを操作するためのモダンなインターフェースが実現されます。これにより、開発効率の向上、学習コストの削減が期待できます。下記の記事では、APIリクエストを受け付ける一般的なサーバー内部の定義や処理フローについて解説していますので、合わせてご参照ください。
APIサーバーの内部動作：リクエストからレスポンスまでの処理の流れ

※Zowe = 操作をAPIに変換する、という形で解説してきましたが、実はこの理解は少し限定的です。Zoweの役割は「操作やコマンドをREST APIに変換する」ことだけではなく、Zowe自体もREST APIを提供しています。またZoweは包括的なプラットフォームで、様々なツールやインターフェースを提供してz/OSへのアクセスのモダナイズを実現できます。詳細は公式ドキュメントをご覧いただければと思います。

参考文献

Zowe 公式ドキュメント
 Zowe GitHub リポジトリ
 IBM® z/OS 管理機能構成要約のガイド - IBM Documentation
IBM z/OS Management Facility Programming Guide - IBM Documentation