Set up a development environment

Edit online

The developer client tool for IBM® watsonx Code Assistant for Z is the extension for Microsoft Visual Studio Code (VS Code) that works in collaboration with IBM Z® Open Editor VS Code extension. IBM Z Open Editor provides language support for the IBM Enterprise COBOL, PL/I, HLASM, REXX, and JCL languages. The IBM watsonx Code Assistant for Z VS Code extension provides you with graphical tools to guide you through the COBOL to Java™ transformation end-to-end. Z Code Assistant 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.

Install the prerequisites

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

Microsoft offers the convenience 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's Semeru Runtime separately instead of using the Visual Studio Code for Java Installer, then IBM Z 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 Zowe Explorer, Z Open Editor, and watsonx Code Assistant for Z VS Code extensions

This section describes 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 Z Open Editor 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.

With the prerequisites in place, you can install the VS Code extensions. After you download and extract the IBM watsonx Code Assistant Developer Tools 2.1 Multilingual package from IBM's Passport Advantage® site you can follow the instructions in the readme.txt file for verifying the code signatures. For more information, see the Z Open Editor documentation.

The watsonx Code Assistant for Z 2.1.0 zip file in the IBM watsonx Code Assistant Developer Tools 2.1 Multilingual package contains the VS Code extensions:

  1. Zowe™ Explorer v2.16.3 vsix file
  2. Z Open Editor v4.4 vsix file
  3. watsonx Code Assistant for Z 2.1.0 vsix file
Note: For best results, do not download the Zowe Explorer v2.16.3 vsix file or Z Open Editor v4.4 vsix file from other sources, other than what is provided by the provided download packages. These versions have been tested to work with other components that are needed for full functionality.

They must be installed in the order as specified because each extension depends on its former entry.

  1. Start VS Code.
  2. Click the Extensions icon on the sidebar.
  3. Drag-and-drop each .vsix file one by one from the compressed file in the specified order into the Extensions view.

    Alternatively, select Install from VSIX from the kebab menu to select each file.

Note: For IBM watsonx Code Assistant for Z v2.0, you must install Z Open Editor v4.3.0.

Complete and verify the installation

To verify your installation, complete the following steps:

  1. Wait for the Welcome to IBM Z Open Editor and IBM watsonx Code Assistant for Z pages 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 Z Open Editor: Welcome.

  2. In the Welcome to IBM Z Open Editor page, 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. The item Zowe Profile is created can be yellow or red as it is not required by watsonx Code Assistant for Z.

  4. In the IBM watsonx Code Assistant for Z page, scroll down to the Prerequisites section.

  5. Ensure that the items Extension Pack for Java or the Language Support for Java by Red Hat VS Code extension is installed, IBM Z Open Editor VS Code extension v4.3.0 or newer is installed and activated, and 64-bit Java SDK version 17 or later have a green checkmark.

  6. Expand the Java section in the Welcome to IBM watsonx Code Assistant for Z page and verify that the "JAVA_HOME" variable is configured with a path to a Java 17 runtime. Z Code Assistant can find Java searching in different locations on your system. However, the Java Language support extension requires a full Java Development Kit version 17 or higher. 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.

  7. Verify that a new view called IBM watsonx Code Assistant for Z appeared in the Explorer activity bar showing Enter API key and Select COBOL, if you migrated from a previous installation and already provided an API key in the past.

If you have any issues, check the guidelines that are provided on 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.

Configuration settings

IBM watsonx Code Assistant for Z can work often as is without any additional configuration options by using the default connection to IBM Cloud and your personal API key. However, if you are connecting to a specific IBM data center or even use a distribution on Cloud Pak for Data then various configuration options are available through VS Code Settings. Two categories of settings relevant for the Z Code Assistant are available: (1) watsonx connectivity settings and (2) general proxy server configuration settings.

To review and change either of these settings, open the VS Code Settings page through the Settings menu or use a keyboard shortcut - cmd plus , on Mac and Ctrl plus , on Windows.

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

Platform

Allows you to switch from the default IBM Cloud platform to a privately hosted IBM Cloud Pak for Data distribution. If you select Cloud Pak, then other settings must be completed as well.

Strict SSL

If you are using IBM Cloud Pak for Data, then you need to deselect this checkbox if your deployment uses self-signed certificates. If your Cloud Pak OpenShift server uses certificates verifiable by a certificate authority then leave it checked. Ask your system administrator for the correct setting.

URL

Provide the base URL for your watsonx services. For the defaultIBM Cloud deployment, leave the default value. Enter a new value only if you are instructed by an IBM representative.

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.

Timeout

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

Code Lens Enabled

After you generate Java code with watsonx, Z Open Editor provides the ability to review the original COBOL code that was used for the transformation. Developers can review this code directly through a Codelens available within the Java editor, that is shown above the Java methods. To disable this function (in case you do not want to see these annotations inside your editor) deselect this setting.

Maximum Program Files

Specify the maximum number of program files for the Prepare COBOL for Transformation operation.

Log Level

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

Welcome Page

Show: If selected, displays IBM watsonx Code Assistant for Z at every editor startup.

JAVA_HOME

If the Welcome to IBM watsonx Code Assistant for Z displays no or an incorrect Java version then provide the absolute path to your Java installation.
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) and 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 a username and a 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 that is separated by a colon and Base64 encoded.

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

Proxy Strict SSL

If your proxy server is 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 deselect this box instead to ignore any network errors that are 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 preceding settings to work, you must select on from the drop-down. Selecting override, reverts to VS Code's default behavior. Some proxy configurations might then not work anymore with IBM watsonx Code Assistant for Z services.
In addition to these settings, you can also configure your proxy server by using the commonly used environment variables such as http_proxy, HTTP_PROXY, https_proxy, HTTPS_PROXY. If you use any of these environment variables, you still need to enable proxy server support by setting Proxy Support to On.

Request an API key

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