Setting up integrations to interact with z/OS

You can use IBM Z Open Editor on your computer without connecting to a z/OS system and download files manually by using an FTP command or similar method. However, you can augment the capabilities of IBM Z Open Editor and enjoy a seamless integration of z/OS with IBM Remote System Explorer API (RSE API) or the Zoweopen in new window open source project. The Zowe project provides great tools that work perfectly with the IBM Z Open Editor.

Note, that with Zowe Explorer 2.0 and Z Open Editor 2.0.2 some changes were introduced to the way this integration is configured that might require some migration from older versions. See the Getting started with Zowe Explorer v2.0 for an overview.

When using IBM Z Open Editor, you can choose how to interact with z/OS with regard to the following aspects:

  • Use RSE API or the Zowe default z/OSMF as the host component
  • Use the command line or graphical interface to interact with z/OS

Next, you can use the following client-side tools based on your decision:

Available host componentTo use command line, install...To use graphical interface, install...
RSE API
  • Zowe CLI, and
  • IBM RSE API Plug-in for Zowe CLI
Zowe Explorer
z/OSMFZowe CLIZowe Explorer

Detailed information about these tools is as follows:

Installing Zowe CLI

The prerequisites for installing Zowe CLI are as follows:

  • Client: Install Node.jsopen in new window version 14, or a later version
  • Host (select one or both):
    • Configure z/OSMF if you plan to use Zowe CLI without RSE CLI plug-in
    • Install and configure IBM Remote System Explorer API if you plan to use Zowe CLI along with RSE CLI plug-in to extend Zowe CLI

You can install Zowe CLI using one of the methods below:

Installing IBM RSE API Plug-in for Zowe CLI

Prerequisites

Before installing IBM RSE API Plug-in for Zowe CLI on your development machine, you must install Zowe CLI 7.0.1 or later. For more information about installing Zowe CLI, see Installing Zowe CLI.

Installing the requisite IBM RSE API z/OS host component

Confirm with your system administrator that the following host components are installed and configured on the z/OS host system:

  • The host component of z/OS Explorer 3.1.1 or 3.2, which is the prerequisite of the RSE API host component.
  • The RSE API host component, which provides a collection of REST APIs that allow a client to work with various components on the z/OS host system, including MVS data sets, z/OS UNIX files and commands, JES jobs, and more.

For information about installing and configuring the RSE API host component, see RSE API documentationopen in new window.

Note: Even if your system administrator has previously installed RSE on your z/OS, an update is needed to get the capabilities described here.

Installing the IBM RSE API Plug-in for Zowe CLI

After installing and configuring the prerequisites and the host component, follow these steps to install the RSE CLI plug-in. You can choose to download the plug-in from IBM as a code-signed archive file to install locally, or do an online installation from the public repository at npmjs.com, which is the repository from which you installed Zowe CLI itself.

Option 1: Download install package from IBM

  1. Navigate to the Mainframe DEV website at https://ibm.github.io/mainframe-downloads/downloads.htmlopen in new window.

  2. Click More info on the IBM Wazi Developer for Red Hat CodeReady Workspaces tab.

  3. In the Code row, click VSCode.

  4. You are then redirected to the Software License Agreement page. Review the License Agreement and click I Agree. You will be prompted to save or open a compressed .zip file in your browser.

  5. Save the compressed .zip file to your workstation.

  6. Extract the compressed .zip file on your workstation. You will find various files in the archive including the Z Open Editor archive as well as a file named ibm-rse-api-for-zowe-cli-v.r.m.tgz.

  7. Optionally, follow the instructions in the included README.txt file to verify the code signature to ensure the file was signed against a trusted IBM certificate.

  8. Install the RSE CLI plug-in by entering the following command in the terminal:

    zowe plugins install path/to/download/ibm-rse-api-for-zowe-cli-v.r.m.tgz
    

    where path/to/download/ibm-rse-api-for-zowe-cli-v.r.m.tgz should be defined with your own file path.

Option 2: Install from npmjs.com

  1. Install the RSE CLI plug-in by entering the following command in the terminal:

    zowe plugins install @ibm/rse-api-for-zowe-cli
    

Validating installation

If the installation was successful, you can see the following message printed in the terminal:

Installed plugin name = '@ibm/ibm-rse-api-for-zowe-cli'

_____ Validation results for plugin '@ibm/ibm-rse-api-for-zowe-cli' _____
This plugin was successfully validated. Enjoy the plugin.

Getting help

After installing the RSE CLI plug-in, you can see all the command options of the plug-in by entering the command zowe rse --help into the terminal.

Updating the IBM RSE API Plug-in for Zowe CLI

Update previous npmjs.com install

If the previous installation of the RSE CLI plug-in was from npmjs.com, run the following command to update to the latest version available on npmjs.com:

zowe plugins update @ibm/rse-api-for-zowe-cli

Update previous .tgz install

  1. Uninstall the older version of RSE CLI plug-in:

    • If the original .tgz file of the older version is still in the original location from the installation, run the following command.

      zowe plugins uninstall @ibm/rse-api-for-zowe-cli
      
    • If the original .tgz file is no longer in the original location from the installation, complete the following procedure:

      1. Use the file explorer to open the .zowe folder in the home directory.

      2. Within the .zowe directory, go to the plugins/installed/node_modules/@ibm directory and delete the rse-api-for-zowe-cli folder.

      3. Navigate to the .zowe/plugins directory, open the plugins.json file in edit mode and remove the @ibm/rse-api-for-zowe-cli section as shown below and save the file.

        "@ibm/rse-api-for-zowe-cli": {
          "package": "@ibm/rse-api-for-zowe-cli",
          "registry": "installation/location",
          "version": "1.0.0"
        }
        
  2. Verify the uninstallation.

    Run the command zowe plugins list. The list of plug-ins should no longer contain @ibm/rse-api-for-zowe-cli upon a successful uninstallation.

  3. Delete rse_meta.yaml file from the .zowe/profiles/rse directory.

  4. Install the new version of RSE CLI plug-in.

    Refer back to Installing the IBM RSE API Plug-in for Zowe CLI to install the new .tgz download of IBM RSE API Plug-in for Zowe CLI.

Moving from .tgz install to npmjs.com install

  1. Follow step 1 - 3 of Update previous .tgz install.

  2. Run command zowe plugins install @ibm/rse-api-for-zowe-cli, which will pull from npmjs.com.

Setting log levels for IBM RSE CLI plug-in

Setting up log levels for the RSE CLI plug-in follows the same method used to set Zowe CLI log levelsopen in new window, and logs are written to the log file location /.zowe/zowe/logs/zowe.log. You can set the log level to adjust the level of detail that is written to the log file.

Important! Setting the log level to TRACE or ALL may result in "sensitive" data being logged.

Environment VariableDescriptionValuesDefault
ZOWE_APP_LOG_LEVELZowe CLI and RSE CLI plug-in logging levelLog4JS log levels (OFF, TRACE, DEBUG, INFO, WARN, ERROR, FATAL)DEBUG

Single sign-on support for IBM RSE CLI plug-in

RSE CLI plug-in has single sign-on (SSO) support using JSON Web Tokens (JWT) that are issued by the RSE API host component to the RSE profile. If the RSE API host component is configured and registered with the Zowe API Mediation Layer (API ML)open in new window, the RSE CLI plug-in also supports SSO using a JWT that is issued to a Zowe CLI base profileopen in new window by the API ML. The JWTs can be used for authentication with the RSE API host component via command line operations as well as operations done within IBM Z Open Editor and Zowe Explorer's z/OS integrations. Learn more about obtaining JSON Web Tokens (JWT) from the RSE API host component with the RSE CLI plug-in or via Zowe Explorer.

Known Issues

If any issues or concerns arise during installation or while working with the RSE CLI plug-in, refer to the known issues documentation for the RSE CLI plug-in here.

Last Updated:
Contributors: Shi Kun Li, Billie Simmons, Lauren Li, Lauren Li, Peter Haumer, BillieJean-Simmons, Peter Haumer, shikunli, Billie Simmons, kmaselli, Billie Jean Simmons, Min Huang