Set up a development environment

Edit online

The developer client tool for IBM® watsonx Code Assistant for Z is the IBM Z® Open Editor extension for Microsoft Visual Studio Code (VS Code). IBM Open Editor provides language support for the IBM Enterprise COBOL, PL/I, HLASM, REXX, and JCL languages. For IBM watsonx Code Assistant for Z, it provides you with graphical tools to guide you through the COBOL to Java™ transformation end-to-end. For watsonx Code Assistant, Z Open Editor also integrates with the Language Support for Java by Red Hat® VS Code extension. This extension gives you access to a complete set of language capabilities that are necessary for the workflows that are described in this documentation.

The following sections describe the most basic steps for installing the prerequisites and VS Code extensions. For a more detailed documentation that explains all the different installation and configuration alternatives see the IBM Z Open Editor Getting Started Guide.

If your current version of Z Open Editor is v3.3, refer to Upgrading from an earlier version as the COBOL-to-Java mapping data structures are changed in v3.4 and requires consideration before upgrading to prevent errors.

Install the prerequisites

The following third-party prerequisites need to be installed on your development system.

Microsoft offers the convenient Visual Studio Code for Java Installer that meets all these prerequisites.

A recommended alternative to OpenJDK is IBM's Semeru Runtime that can be downloaded here, which is the same runtime that you would use on z/OS®.

If you decide to install VS Code and the IBM Semeru Runtime separately instead of using the Visual Studio Code for Java Installer, then IBM Open Editor guides you in installing the Microsoft VS Code Extension Pack for Java as described in Complete and verify the installation.

Ensure that your "JAVA_HOME" environment variable is configured to point to the Java 17 runtime you installed previously.

Install Z Open Editor

With the prerequisites in place, you can install the IBM Open Editor extension. If you downloaded IBM watsonx Code Assistant for Z packages from IBM's Passport Advantage® site, then the code-signed IBM extensions that are needed are included. Follow the instructions in the readme.md file to verify the extensions' integrity and install them even in an air gap environment. For more information, see the Z Open Editor documentation.

If you are connected to the internet and do not require code signature verification, then you can install Z Open Editor directly from the VS Code Marketplace with the following steps:

  1. Start VS Code.

  2. Click the Extensions icon on the sidebar.

  3. Search for "IBM Open Editor" in the search box.

  4. Click Install.

Complete and verify the installation

To verify your installation, complete the following steps:

  1. Wait for the "Welcome to IBM Open Editor" page to appear. If you used Z Open Editor before and the Welcome page is unavailable, select the menu option View > Command Palette.. and type or select "IBM Open Editor: Welcome".

  2. Scroll down to the "Prerequisites" section.

  3. Ensure that the items "64-Bit Java 11 or higher found" and "Zowe™ Explorer extension is installed and activated" have a green checkmark.

  4. Expand the Java section in the Welcome page and verify that the "JAVA_HOME" variable is configured with a path to a Java 17 runtime. Z Open Editor can find Java searching in different locations on your system. However, the Java Language support extension that is installed with the prerequisites requires the "JAVA_HOME" variable to be used and the Java version to be 17 or higher.

  5. The item "Zowe Profile is created" can be yellow or red as it is not required by watsonx Code Assistant for Z.

  6. Scroll back to the beginning of the Welcome page and expand the section "New: IBM watsonx Code Assistant for Z in Z Open Editor"

  7. Select Enable the IBM watsonx Code Assistant with Z in Z Open Editor (requires an account)".

  8. If the Microsoft VS Code Extension Pack for Java is not installed or activated, then a dialog opens that guides you through the installation. Click Install to install the full extension pack. After the installation completes, select the Enable the IBM watsonx Code Assistant with Z in Z Open Editor (requires an account) again to complete enabling the feature.

  9. Verify that no error messages appear and the checkbox remains selected.

  10. Verify that a new view called IBM WATSON CODE ASSISTANT FOR Z was opened in the Explorer activity bar showing Select COBOL.

If you have any issues, check the guidelines that are provided by the Welcome page. If problems with the Java installation were found, then dialog prompts guide you through the issue. See the IBM Z Open Editor documentation here for more details for troubleshooting and configuring Java.

Advanced configuration settings

The watsonx Code Assistant for Z integration with Z Open Editor provides various configuration options that can be managed via VS Code Settings. There are two categories of settings relevant for the Code Assistant: (1) watsonx settings and (2) proxy server configuration settings.

To review and change either of these open the VS Code Settings page through the Settings menu or using the shortcut would be cmd plus , on Mac and Ctrl plus , on Windows.

watsonx settings

In the VS Code Settings page, type watsonx in the Search field. The following settings appear under the label Zopeneditor > watsonx > watsonx Code Assistant for Z.
Settings Description

Enable

You selected this option on the Welcome page in the previous section to activate watsonx Code Assistant for Z within Z Open Editor. Deselecting the option disables all watsonx functionality.

URL

Provide the base URL for your watsonx services. For the default IBM Cloud deployment, do not modify it and leave the default value. Only enter a new value if you are instructed by an IBM representative.

Log Level

Determines the amount of detail the log contains in the VS Code Output view. For more information, see the Troubleshooting section.

Timeout

The time in milliseconds for the editor to wait for a response from the watsonx server. Only enter a new value if instructed by an IBM representative.

Code Lens Enabled

After you generate Java code with watsonx, Z Open Editor will provide the ability to review the original COBOL code that was used for the transformation. Developers can review this code directly via a Codelens available within the Java editor, shown above the Java methods that were generated. To disable this functionality, in case you do not want to see these annotations inside your editor, un-check this setting.

Authentication URL

A URL that is used to authenticate your user account and API key. For the default IBM Cloud deployment do not modify it and leave the default value. Only enter a new value if you are instructed by an IBM representative.
Proxy server settings
If your VS Code installation requires the use of a proxy server to access watsonx services over the internet, then you must configure such a proxy server in your VS Code settings. In the VS Code Settings page proxy in the Search field. The following settings appear under the label Http:
Settings Description

Proxy

Provide a URL to your proxy server here. Include the correct protocol (http or https) as well as the port number. If required, you can also include the authorization username and password as part of the URL.

Note: These would be stored in your personal VS Code settings in clear text. Examples for such urls would be <http://proxy-server.com:8123> or <https://user1:password@proxy-server.com:8123>.

Proxy Authorization

Instead of providing username and password as part of the proxy URL, you can also provide it in this setting in the format the proxy server would expect it in a so-called "Proxy-Authorization" header. Check with your proxy administrator about the details. An example, for the content of this setting would be Basic em9wZW5lZGl0b3ItZmFuOmxvdmUtaXQ=, which indicates that the authentication protocol is "Basic" with the username and password separated by a colon and base64 encoded.

Note: This setting would be stored in your personal VS Code settings and can be easily be decoded.

Proxy Strict SSL

If your proxy server has been configured to use a self-signed SSL certificate, then you must import this certificate to your local system, by using the method defined by your proxy administrator for your operation system. If you cannot import these certificates you can uncheck this box instead, to ignore any network errors related to certificates.

Note: This is not recommended and not secure. It will also impact all http requests from all your other VS Code extensions installed. Only deselect this setting if instructed by your proxy administrator.

Proxy Support

For any of the above settings to work you must select the value on in the drop down. Selecting override, will revert back to VS Code's default behavior. Some proxy configuration might then not work anymore with IBM watsonx services.

Request an API key

Follow the instructions for obtaining an API key at Getting started with watsonx Code Assistant.