Installing Wazi Developer for VS Code

Complete the following steps to install Wazi Developer for VS Code on your workstation:

Prerequisites
Download IBM Wazi Developer for VS Code
Install Zowe Explorer
Install IBM Z Open Editor
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 version 1.44 or later: As Wazi Developer for VS Code is delivered as a set of VS Code extensions instead of a stand-alone IDE, you must install and configure VS Code first. We recommend using always the latest VS Code version available. However, although the required minimal version is 1.44.0 we recommend to use at least 1.45.1, which includes fixes in VS Code User Settings that can impact IBM Z Open Editor. If you do not have VS Code installed we recommend using the Visual Studio Code for Java Installer provided by Microsoft as it automatically downloads and installs a Java SDK together with VS Code. (See, but skip the next bullet for the Java dependency, if you use this option.) 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. We recommend installing VS Code for Java as described above, but if you already have VS Code or want to install Java yourself then you can choose from the following options:
- Oracle Java 8 or the LTS versions 11 of Oracle Java
- Version 8, 11, or 17 of the OpenJDK. If you are using version 1.1 or newer of Z Open Editor, you can also use just a Java Runtime Environments (JRE) as well.
- Newer versions of Java should also work, but are not as rigorously tested for Z Open Editor as Java 8 and 11.
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.33.3 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 Developer for VS Code

Download the client of Wazi Developer for VS Code from Mainframe DEV according to Procedure for downloading installation packages from Mainframe DEV. Extract the downloaded <license>_Wazi_Developer_for_VSCode_<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.

The <license>_Wazi_Developer_for_VSCode_<version>.zip you extracted above contains the .sig and .pem files that are used to verify the binary files.
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
```
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.19.0 or later (1.20.0 is recommended) 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.

Note: Starting from IBM Wazi Developer 1.1.0, the user build functionality is part of the IBM Z Open Editor VS Code extension. User build allows z/OS developers to run personal builds within Wazi Developer using the IBM Dependency Based Build (DBB) tool. Follow user build documentation to learn more.

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:

Click the Extensions icon on the activity bar in VS Code to open the Extensions view.
Click the ... icon on the upper-right corner in the Extensions view to reveal a drop-down menu of more actions.
In the drop-down menu that appears, click Install from VSIX....
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

The COBOL, PL/I, and HLASM language servers utilized by IBM Z Open Editor were implemented using the Java programming language. Therefore, a Java Runtime is required to be available via settings or the program path to start in VS Code. The IBM Z Open Editor extension utilizes VS Code Settings properties, which can be added to VS Code 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.

Selecting the Java installation to use

Before starting a language server the language server clients in the IBM Z Open Editor VS Code extension try looking in different places to find a matching Java installation. They will look in the following places in this specific order and pick the first Java installation they can find that is at least Version 8 and 64-Bit. If it finds a Java that fails the test against these criteria it will continue searching:

The zopeneditor.JAVA_HOME VS Code user setting.
The java.home VS Code user setting.
The JAVA_HOME environment variable.
The PATH defined for the environment in which Z Open Editor runs (i.e. you default Windows or MacOS path)
A typical platform-specific location. For example, on MacOS it will execute the /usr/libexec/java_home -V and on Windows the where java.exe commands to locate a valid Java installation.

As you can see user settings always take precedence over the other options listed, which enables you to specify a different Java version for IBM Z Open Editor than the default on your computer in case you have installed multiple version. If you used the recommended Visual Studio Code for Java Installer the java.home user setting was set by this installer.

If Java cannot be located check the VS Code Output view's Z Open Editor tab for any error and try to fix the problem by either setting the JAVA_HOME environment variable or create an entry in your VS Code user settings.

To define a user setting use the Preferences > Settings menu and either locate the setting in the graphical editor under IBM Z Open Editor or edit the setting json file directly by adding an entry as follows using an absolute path name to the Java installation directory.

On Mac:

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

On Windows:

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

Configuring the Java memory allocation

By default, the language server client that starts the individual language servers for COBOL, PL/I, HLASM, or REXX allocates a maximum of 512 MB of memory for each. The language servers will consume much less memory at startup, and then allocate and free memory when parsing programs. However, they might run out of memory when parsing very large program files and reach the predefined limit. To allow allocating more memory, use the following VS Code setting to specify a new maximum value:

"zopeneditor.server.memoryAllocation": 640

Keep in mind that this value is for each language you use, so when using both COBOL and PL/I, you might end up with a consumption of double the amount specified. If you are working with smaller programs or your computer might not support such a large amount of memory, you can also try values smaller than 512 with this setting.

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.