Installing Wazi Development Client

Complete the following steps to install Wazi Development Client on your workstation:

  1. Prerequisites

  2. Download IBM Wazi Development Client

  3. Install Zowe Explorer

  4. Install IBM Z Open Editor

  5. Install IBM User Build

  6. Install IBM Z Open Debug

Prerequisites

Review the IBM Z Open Editor License Agreement and Third Party Notices before downloading.

Prerequisites for the installation:

  • Visual Studio Code: As Wazi Development Client is delivered as a set of VS Code extensions instead of a stand-alone IDE, you must install and configure VS Code first. For information about installation and configuration of VS Code, see its documentation.

  • Java SDK version 8 or later - 64 bit: The COBOL, PL/I, and HLASM language servers included in this extension are implemented in Java. Therefore, you need to install and configure a 64-bit Java SDK in order to start it successfully.

    • You can use Oracle Java SDK 8 or the LTS version 11 of Oracle Java. Alternatively, you can use version 8 or 11 of the OpenJDK.

      Note, in all cases, you need to download and configure a full JDK and not just a Client Runtime version of Java. The language servers will not work with only a Client Runtime version.

    Various settings are provided to configure how the extension uses Java. See the Configuring Java section below for more details. Contact us if you run into any issues with a specific Java version.

  • (Recommended) Git: To use the features that involve Git, you must install Git and have it available in your system path so that VS Code can display it. On Macs, Git comes out of the box. On Linux, you can install Git with your distribution's package manager. On Windows, you can get Git from https://git-scm.com.

  • (Recommended) Zowe CLI 6.11 or later: To make use of Zowe to open and edit files directly from z/OS® MVS™ or USS via command line, you need Zowe CLI and host components configured. For more information, see Setting up integrations to interact with z/OS.

Downloading IBM Wazi Development Client

Download the client of Wazi Development from Mainframe DEV according to Procedure for downloading installation packages from Mainframe DEV. Extract the downloaded wazi-development-client-<version>.zip on your machine.

If you want to check code signing signatures for the downloaded binary files, refer to the following procedure. Install OpenSSL if you have not done so.

  1. The wazi-development-client-<version>.zip you extracted above contains the .sig and .pem files that are used to verify the binary files.

  2. Check the certificate validity.

    1. To view the certificate details, issue the following command:

      $ openssl x509 -text -in wazi-certificate.pem -noout

    2. To view the public key details, issue the following command:

      $ openssl rsa -noout -text -inform PEM -in wazi-public.pem -pubin

    3. Compare the exponent of the public key and the certificate to see that the public key is indeed the one within the certificate. You can also use any other certificate viewer such as Mac OS Preview.

    4. To check the validity of IBM public certificate, issue the following command:

      $ openssl ocsp -no_nonce -issuer wazi-chain0.pem -cert wazi-certificate.pem -VAfile wazi-chain0.pem -text -url http://ocsp.digicert.com -respout ocsptest

      If the certificate is valid, the output is:

      Response verify OK

  3. Verify the downloaded binary files.

    To verify the files by using the signature and public key files, issue the following command:

    $ openssl dgst -sha256 -verify wazi-public.pem -signature ${binary-filename}.sig ${binary-filename}

    For example, to verify zopeneditor-1.0.0.vsix, issue:

    $ openssl dgst -sha256 -verify wazi-public.pem -signature zopeneditor-1.0.0.vsix.sig zopeneditor-1.0.0.vsix

    If the binary is verified successfully, the output is:

    Verified OK

Installing Zowe Explorer

IBM Z Open Editor requires the Zowe Explorer VS Code extension 1.5.2 or later as a prerequisite. When you install IBM Z Open Editor, it will automatically try to download Zowe Explorer from the VS Code Marketplace for you. If you are working offline, then first install the Zowe Explorer VSIX file Zowe.vscode-extension-for-zowe-<version>.vsix that you extracted from wazi-development-client-<version>.zip into your VS Code instance. You can follow the VS Code documentation for installing from a .vsix file.

Installing IBM Z Open Editor

IBM Z Open Editor provides support for IBM enterprise languages. You can install IBM Z Open Editor from either of the following two approaches.

You can always get the latest version of IBM Z Open Editor from either Mainframe DEV or VS Code Marketplace. By default, VS Code checks for extension updates and installs them automatically. You can disable auto-update as described in Extension auto-update.

Important: Before you install IBM Z Open Editor, you need to have a full Java SDK installed and configured on your development machine. See the Prerequisites section above and the Configuring Java for IBM Z Open Editor section.

Installing IBM Z Open Editor from a .vsix file

Install zopeneditor-<version>.vsix that you extracted from wazi-development-client-<version>.zip into your VS Code instance as follows:

  1. Click the Extensions icon on the activity bar in VS Code to open the Extensions view.

  2. Click the ... icon on the upper-right corner in the Extensions view to reveal a drop-down menu of more actions.

  3. In the drop-down menu that appears, click Install from VSIX....

  4. Use the file picker that pops up to navigate to and select the VSIX file you downloaded, and then click Install.

The extension should be installed from the VSIX file. For more information, see VS Code documentation for installing from a VSIX.

Installing IBM Z Open Editor from the VS Code Marketplace

Alternatively, as IBM Z Open Editor is also available free of charge in the VS Code Marketplace, you can get IBM Z Open Editor in either of the following ways.

  • Start VS Code, open the Extensions view by clicking the Extensions icon on the activity group or by clicking the menu File > Preferences > Extensions, and search for IBM Z Open Editor. Click the Install button and wait for the installation to complete.

  • Go to the VS Code Marketplace website that hosts IBM Z Open Editor. Click the Install button and wait for the installation to complete.

Verifying the installation of IBM Z Open Editor

To quickly test whether IBM Z Open Editor is installed correctly, you can open a COBOL, PL/I, or HLASM program file on your machine. If you do not have such files on your machine, you can clone the sample repository as described in the Exploring the sample files section and open its COBOL, PL/I, or HLASM program files. If you see syntax highlighting on COBOL, PL/I, or HLASM code, the extension is working correctly.

Configuring Java for IBM Z Open Editor

As mentioned above, the COBOL, PL/I, and HLASM language servers used by IBM Z Open Editor were implemented using the Java programming language. Therefore, a Java Runtime is required to be available in the program path to start in VS Code. The IBM Z Open Editor extension uses VS Code Settings properties, which can be added to VS Code workspace or to user settings, to configure which and how Java should be used. These settings allow you to select the specific installation of Java to pick, in case you have several installations, as well as set parameters such as how much memory you want the extension to use. You can specify the settings by editing the settings.json file for your workspace or in the user preferences settings directly.

Selecting the Java installation to use

The language server clients running in the IBM Z Open Editor VS Code extension try looking in different places to find a matching Java. By default, it looks for Java using the JAVA_HOME environment variable if no settings were provided for the user to the current workspace. If that was not defined, it finds Java in the user's PATH. If neither the JAVA_HOME environment variable nor the user's PATH contains a valid Java installation, you will see an error message that shows the language server for either COBOL, PL/I, HLASM might not be started.

To fix the problem, either provide the missing value or define a Settings entry in your VS Code user or workspace settings. The setting always has precedence over the other two options described above. In other words, it tries to use that Java installation first. This allows you to specify a different Java for IBM Z Open Editor other than the default of your computer.

The configuration for the alternative JAVA_HOME will accept a path to the Java SDK, for example:

On Mac:

"zopeneditor.JAVA_HOME": "/Library/Java/JavaVirtualMachines/jdk1.8.0_231.jdk/Contents/Home"

On Windows:

"zopeneditor.JAVA_HOME": "C:\\Program Files\\Java\\jdk1.8.0_231"

Configuring the Java memory allocation

By default, the language server clients that start the language servers for COBOL or PL/I allocate a maximum of 512 MB of memory for each. In other words, they start using much less memory in the beginning, but you might run out of memory when working on large program files; or your computer might not support such a large amount of memory in the first place. To have more flexibility in how much memory the language servers are allowed to allocate, use the following VS Code settings to specify the maximum value. When you use both COBOL and PL/I, you need to double the amount specified.

"zopeneditor.server.memoryAllocation": 1024

Installing IBM User Build

You can use the IBM User Build VS Code extension to run user builds within Wazi Development using the IBM Dependency Based Build (DBB) tool.

Before you install IBM User Build you need to have IBM Z Open Editor installed as a prerequisite. If you have not done that, refer to the steps above.

Install userbuild-<version>.vsix that you extracted from wazi-development-client-<version>.zip into your VS Code instance. You can follow the VS Code documentation for installing from a .vsix file.

To upgrade IBM User Build on your workstation, download the latest wazi-development-client-<version>.zip from Mainframe DEV, extract the compressed file, and install the .vsix file.

Installing IBM Z Open Debug

You can use the IBM Z Open Debug VS Code extensions with z/OS Debugger to debug z/OS COBOL and PL/I applications in a remote VS Code client.

Install the following VS Code extensions that you extracted from wazi-development-client-<version>.zip into your VS Code instance (V1.43 or later):

  • zopendebug-<version>.vsix

  • zopendebug-profileui-<version>.vsix

You can follow the VS Code documentation for installing from a .vsix file.

To upgrade IBM Z Open Debug on your workstation, download the latest wazi-development-client-<version>.zip from Mainframe DEV, extract the compressed file, and install the .vsix files.