Getting started with IBM Z Open Editor

The procedure to get started with IBM Z® Open Editor is summarized as follows:

1. Get the latest version of Microsoft Visual Studio Code (VS Code)
2. Install the prerequisites (a Java™ 17 runtime environment as a minimum)
3. Install the IBM Z Open Editor VS Code extension from the VS Code Marketplace
4. (Optional) Set up integrations for extended capabilities, such as installing IBM RSE API Plug-in for Zowe CLI to interact with z/OS

Privacy notice

IBM Z Open Editor is provided free of charge, but we ask you to provide us feedback via the various means available including:

• Submit an issue in our GitHub repository
• Provide a review in the VS Code Marketplace
• Keep the built-in telemetry and crash reports enabled

This editor uses Microsoft VS Code's Telemetry solution that collects anonymized telemetry data, which is used to help understand how to improve the product. While we appreciate the insights this data provides, we also know that not everyone wants to send usage data and you can disable telemetry as described in Disable Telemetry Reporting. You can also read IBM®'s General Privacy Statement to learn more about our policies.

This current release of IBM Z Open Editor will collect anonymous data for the following events:

• Activation of this VS Code extension
• Deactivation of this VS Code extension
• Opening, closing and saving files of a specific language such as COBOL, PL/I, HLASM, REXX, JCL
• Resolving of include files and assembler macros: success or failure
• Using common language server operations such as code completion, references, definition, rename
• Starting a user build
• Responding to the feedback dialog
• Activating trial or full unlock licenses

Such events are logged with the following information:

• Event time
• Operating system and version
• Country or region
• Anonymous user and session ID
• The type of editor used (VS Code, Eclipse Theia, Red Hat Dev Spaces)
• Version numbers of Microsoft VS Code and IBM Z Open Editor
• The major Java version and vendor used by the language servers
• The name of the Z programming language used
• The name of the operation performed
• The type of z/OS protocol used (z/OSMF vs RSE API)

Installing the IBM Z Open Editor VS Code extension

IBM Z Open Editor is an extension for VS Code. Before installation, ensure that you have installed and configured the prerequisites, most importantly a Java runtime as main 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 downloading.

Prerequisites for the installation:

• Visual Studio Code version 1.91.0 or later: IBM Z Open Editor is delivered as an extension to VS Code instead of a stand-alone editor, so you must install and configure VS Code first. We recommend always using the latest version of VS Code available. If you do not have VS Code installed we recommend using the Visual Studio Code for Java Installer provided by Microsoft, because it automatically downloads and installs a Java SDK together with VS Code. (You can skip the next bullet about Java dependency if you use this option.) For information about installation and configuration of VS Code, see its documentation.

• Java SDK or JRE version 17 or later - 64 bit: The language servers included in this extension are implemented in Java. Therefore, you need to install and configure a 64-bit Java SDK or Runtime in order to start the extension 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:

  • We highly recommend using versions 17 or 21 of IBM's Semeru Runtime that can be downloaded here. IBM Semeru Runtimes enable developers to build and deploy Java applications that will start quickly and deliver great performance - all while using less memory. We use it ourselves for development.
  • Alternatively, you can use the LTS versions 17 or 21 of Oracle Java or the OpenJDK.
  • Newer versions of Java should also work, but 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 Explorer VS Code extension 3.0.0 or later and Zowe CLI 8.0.0 or later (optional): To make use of Zowe to open and edit files directly from z/OS® MVS™ or z/OS UNIX System Services, you need 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. Once installed, you can access z/OS resources as documented in Interacting with z/OS.

  Note: 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) 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.

Installing IBM Z Open Editor

There are three ways to download and install IBM Z Open Editor. If you are planning to use or evaluate the non-warranty and unsupported version of IBM Z Open Editor then 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 entitled to technical support for Z Open Editor in any other way, we recommend you download from our Mainframe DEV Download site. This convenient zip file download includes code signing signature files and all related software components such as the IBM Z Open Debug VS Code extension, the IBM RSE API Plugin for Zowe CLI, and Zowe CLI.

Installing 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:

• Start VS Code, open the Extensions view by clicking the Extensions icon on the activity bar, or by clicking the menu File > Preferences > Extensions, and search for IBM Z Open Editor.
• Go to the VS Code Marketplace website that hosts IBM Z Open Editor.

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

Installing 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.

Installing 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.

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, 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.

Configuring Java

The IBM Z Open Editor Welcome page will show 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 via 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.

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 that is at least version 17 and 64-bit. If it finds a Java that fails the test against these criteria, it will continue searching.

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/jdk17/Contents/Home"

On Windows:

"zopeneditor.JAVA_HOME": "C:\\Program Files\\Java\\jdk17"

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.

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. We list a couple of examples that we test with, but there might be more configurations that the editor would also work in.

Red Hat Dev Spaces for OpenShift

Our recommended cloud-based development environment is Red Hat OpenShift Dev Spaces that provides a cloud-based development environment that is fully integrated into Red Hat OpenShift. To try Z Open Editor for free in Red Hat OpenShift Dev Spaces, you can sign up for a 30-day trial of the OpenShift Sandbox and Red Hat Developer Sandbox. We have a full tutorial for signing up and using Z Open Editor here.

GitPod

GitPod is a cloud-based IDE offering by the GitPod company that can also utilize VS Code as the browser-based editor and integrate with all the major Git service providers such as GitLab, GitHub, and Bitbucket. After you sign in with an account from either of these Git services, you can easily start a workspace with Z Open Editor.

To try it out with our code samples repository, use this link https://gitpod.io/#https://github.com/phaumer/zopeneditor-sample. The workspace will start up and load a custom image prepared by our team that even contains Zowe CLI and Ansible CLI. After the editor is up, you might have to click F1 and select the command View: Focus Activity Bar to bring in the sidebar that allows you to find our sample programs. Z Open Editor was automatically installed for this workspace, so you can just open a program and start editing. Note that this is a paid-for service, but the first hours are free.

GitHub Codespaces

Z Open Editor can also be used with all of its capabilities in Microsoft's GitHub Codespaces. After your start your development environment in Codespaces, you can find and install Z Open Editor from the integrated marketplace. You can also use extension recommendations.

Try it by using this link https://github.com/codespaces/new?machine=basicLinux32gb&repo=160883618&ref=wazi-main&location=WestUs2 that loads our Z Open Editor sample repository. After the editor is up, click Install in the dialog that asks "Do you want to install the recommended extensions for this repository?". Note that this is a paid-for service, but the first hours are free.

Pure web-based editing in vscode.dev and github.dev

Z Open Editor can be used as a pure web extension with limited capabilities when using Visual Studio Code in a browser, such as on vscode.dev or github.dev.

Try it by going to https://vscode.dev/github/IBM/zopeneditor-sample and confirming in the dialog to install the recommended extensions by clicking Install. No language server capabilities will be available, but syntax highlighting for all our supported languages.