Installing IBM Developer for z/OS on VS Code

IBM Developer for z/OS on VS Code includes IBM Z® Open Editor as one of its key components. IBM Z Open Editor is an extension for VS Code. Before installation, ensure that all prerequisites are installed and configured, most importantly, a Java runtime, as core parts of the extension are implemented in the Java programming language.

Prerequisites

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

Prerequisites for the installation:

  • VS Code version 1.102.3 or later (recommended version: 1.105.1): IBM Z Open Editor is delivered as an extension to VS Code rather than as a stand-alone editor. Therefore, VS Code must be installed and configured first. It is recommended to use the latest available version of VS Code. If VS Code is not already installed, consider using the Visual Studio Code for Java Installer provided by Microsoft. This installer automatically downloads and installs both a Java SDK and VS Code. The next bullet about the Java dependency can be skipped if this option is used. For information about installation and configuration of VS Code, refer to its documentation.

  • Java SDK or JRE version 21 or later - 64 bit: The language servers included in this extension are implemented in Java. To start the extension successfully, a 64-bit Java SDK or Runtime must be installed and configured. It is recommended to install VS Code for Java, as described in the preceding section, since it automatically includes the required Java SDK. However, if VS Code is already installed or if manual installation is preferred, the following options are available for installing Java:

    • Use version 21 of IBM's Semeru Runtime available for downloaded here. IBM® Semeru Runtimes support building and deploying Java applications that start quickly, deliver strong performance, and consume less memory. These runtimes are also used internally during development.

    • Alternatively, you can use the LTS version 21 of Oracle Java or the OpenJDK.

    • Newer versions of Java beyond 21 are expected to work, but they are not tested with Z Open Editor.

    Various settings are provided to configure how the extension uses Java. See the Configuring Java section below for more details.

  • Zowe client software: To make use of Zowe to open and edit files directly from z/OS® MVS™ or z/OS UNIX System Services, you must have Zowe client software and host components configured. More information on setting up Zowe can be found at Setting up integrations to interact with z/OS. After installation, you can access z/OS resources as documented in Interacting with z/OS.

    • Zowe Explorer VS Code extension v3.2.2 or later. When you install IBM Z Open Editor from the VS Code Marketplace into your VS Code, the latest version of the Zowe Explorer VS Code extension is automatically co-installed as it is a mandatory prerequisite for running Z Open Editor.

    • (Optional) Zowe CLI v8.11.0 or later. Z Open Editor and Zowe Explorer can operate completely independently of it.

  • (Optional) 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.

Downloading IBM Developer for z/OS on VS Code

Download the client of IBM Developer for z/OS on VS Code from Mainframe DEV according to Procedure for downloading installation packages from Mainframe DEV. Extract the downloaded IBM_Developer_for_z/OS_on_VSCode.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 IBM_Developer_for_z/OS_on_VSCode.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 thhe 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

Install IBM Z Open Editor

There are several ways to download and install IBM Z Open Editor. If you plan to use or evaluate the non-warranted and unsupported version, you can install it directly from the VS Code Marketplace or the Open VSX Registry.

If you are an IBM Developer for z/OS Enterprise Edition or IBM Application Delivery Foundation for z/OS customer, or are otherwise entitled to technical support for Z Open Editor in any other way, it is recommended to use one of the extension packs, which install several VS Code extensions automatically. You can also download a convenient ZIP file from the Mainframe DEV Download site.

The ZIP files include all the VS Code extensions that you will find in the VS Code Marketplace and Open-VSX Extension Packs listed in detail below. In addition they include components that are not VS Code extensions and therefore not available through the extension packs. They are command line interface tools that augment what you can do with the VS Code extensions for issuing ad-hoc commands to z/OS from your workstation or even use them for scripting automation. We include the Zowe CLI together with Zowe CLI plugins for IBM RSE API and IBM CICS. These CLI tools are not required for the VS Code extensions to function, but provide added value. In particular the RSE API Plugin is provided by IBM and not part of the Zowe project and documentation and therefore only fully documented here in this online documentation.

Finally, the ZIP files also contain code signing signature files that you can use to verify the integrity of the downloaded files. The README.txt file included in the ZIP file explains in detail how to verify all the included binaries with the signature files one by one.

Install IBM Z Open Editor from a VSIX file

If you have downloaded the Mainframe DEV Center's Download for VS Code, you can install it with the following steps in VS Code.

  1. Unzip the downloaded zip file.

  2. Open the README.txt file in a text editor and follow the (optional) steps described there to verify the individual files with the provided code signing signatures.

  3. To install the zopeneditor-\<version\>.vsix file in VS Code, click the Extensions icon in VS Code's activity bar to open the Extensions view.

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

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

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

  7. The extension should be installed from the VSIX file.

Install IBM Z Open Editor from the Open VSX Registry

If you already have or want to configure VS Code to use the alternative public or a private on-site Open VSX Registry, or if you are using a VS Code compatible editor such as VSCodium or Eclipse Theia that use it by default, then you can find and install IBM Z Open Editor and install it from there as well. See the Open VSX documentation for how to configure and use this registry instead.

Install IBM Z Open Editor from the VS Code marketplace

When the correct Java runtime is installed and configured, you can use either of the following ways to get versions of IBM Z Open Editor that are available in the VS Code Marketplace:

Then, click the Install button and wait for the installation to complete.

Installing from an extension pack

Two extension packs are available that include Z Open Editor along with various other extensions, providing customers a convenient way to install and manage IBM's family of VS Code tools with just a few mouse clicks.

To learn more about each of these extensions, navigate to the links provided in the description of each extension pack.

To install an extension pack, follow the same instructions used for installing Z Open Editor from the VS Code Marketplace or Open-VSX:

  • Search for the pack in the VS Code Extension view or on the marketplace's web page.

  • Click the Install button.

After the extension pack and its included extensions are installed, you can enable or disable each individual extension in the VS Code Extension view. When a new version of any extension is published, updates are installed automatically. Reinstallation of the extension pack is not required.

Verify 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, HLASM, REXX, or JCL 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, HLASM, REXX, or JCL program files. If you see syntax highlighting on COBOL, PL/I, HLASM, REXX, or JCL code, the extension is working correctly.

Configure Java

The IBM Z Open Editor Welcome page shows you if Java was found successfully. To open the Welcome page, press Ctrl+Shift+P (Windows) or Cmd+Shift+P (MacOS), and type IBM Z Open Editor: Welcome. Check the prerequisites table on the page, and click the Java section to expand.

The COBOL, PL/I, HLASM, REXX, and JCL language servers used by IBM Z Open Editor were implemented using the Java programming language. Therefore, a Java Runtime is required to be available through settings or 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 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.

Select the Java installation to use

Before you start a language server, the language server clients in the IBM Z Open Editor VS Code extension look in several locations to find a matching Java installation. They search in the following order and select the first Java that is version 21 or higher and 64-bit. If a Java installation fails either criterion, the search continues until a suitable version is found.

  1. The zopeneditor.JAVA_HOME VS Code user setting.

  2. The java.home VS Code user setting.

  3. The JAVA_HOME environment variable.

  4. The PATH defined for the environment in which Z Open Editor runs, that is, you default Windows or MacOS path.

  5. A typical platform-specific location. For example, on MacOS, execute the /usr/libexec/java_home -V; on Windows, run 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 versions. If you used the recommended Visual Studio Code for Java Installer, the java.home user setting was set by this installer. Also note that the methods at the end of the list require a significant amount of time as they are executing programs on your system. To improve startup times you should consider user settings as they provide the best startup performance.

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 creating 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 MacOS:

"zopeneditor.JAVA_HOME": "/Library/Java/JavaVirtualMachines/jdk21/Contents/Home"

On Windows:

"zopeneditor.JAVA_HOME": "C:\\Program Files\\Java\\jdk21"
Configure 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 consume much less memory at startup, and then allocate and free memory when you parse programs. However, they might run out of memory when you parse very large program files and reach the predefined limit. To allow allocation of 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.

Using IBM Z Open Editor in cloud-based editors

Z Open Editor can be installed and used with various cloud or browser-based editing environments that utilize VS Code as the editor. See Overview to using Cloud and Browser-based platforms for some quickstart tutorials and configuration examples.