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. IBMZ 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 VS 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 Java 17 runtime that is installed previously. This variable must be added to the system's environment and the user's environment.

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 v5.4.0, 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.5.0 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.5.0 zip file in the IBM watsonx Code Assistant Developer Tools 2.5.0 Multilingual package contains the VS Code extensions:

  1. Zowe™ Explorer v3.1.0 vsix file
  2. Z Open Editor 5.4.0 vsix file
  3. watsonx Code Assistant for Z 2.5.0 vsix file
Note: For best results, do not combine different versions of Z Code Assistant, Zowe Explorer, and Z Open Editor unless you have received a special fix pack from tech support. These versions have been tested to work with other components that are needed for full functionality.
Note: If the current version of Z Open Editor is v5.4.0, then refer to Upgrading Z Open Editor from an earlier version as the COBOL-to-Java mapping data structures are changed in v3.4 and require consideration before upgrading to prevent errors.

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.5.0, you must install Z Open Editor v5.4.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 17 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 (recommended) or the Language Support for Java by Red Hat VS Code extension is installed, IBM Z Open Editor VS Code extension v5.3.0 or newer is installed and activated, and 64-bit Java JDK 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

The following two IBM Cloud deployments are available:

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.
Translate Explanations Translate explanations to the locale of VS Code before displaying them in the panel view.
Include Comments Keeps any comments within your source code when requesting an explanation from the generative AI solution.
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 the default behavior of VS Code. 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.

Configuring the database connectivity

When generating Java logic, you can choose between two technologies for database connectivity:

  • Java Database Connectivity (JDBC), the default option that is commonly used off the mainframe platform since it offers greater flexibility, portability, and ease of use in modern application development.
  • SQL Java (SQLJ), typically used in the mainframe context since it offers static SQL benefits, improves performance and security, and integrates seamlessly with IBM Db2 for z/OS.
Note:

When using SQLJ as the database connectivity type, CodeLens for COBOL preview and generate method is not available.

Configuring the JDBC driver

Regardless of whether you select SQLJ or JDBC as the database connectivity, it is mandatory to declare a JDBC driver in the build file. The recommended option is to use the IBM Db2 [com.ibm.db2].

 <dependency>
            <groupId>com.ibm.db2</groupId>
            <artifactId>jcc</artifactId>
            <version></version>
    </dependency>

Using the wcaz-transform.yaml settings file

The wcaz-transform.yaml settings file is added to the transform folder in the .wca4z tree.

The following is a sample wcaz-transform.yaml settings file.

database_connectivity:
  connection_type: JDBC

If the value of connection_type is set to SQLJ, and the generated class contains SQL statements, then a .sqlj file is generated during a COBOL-to-Java transformation. This file contains the code that performs the calls to the database. To run this code, you must first translate the .sqlj files into .java files using one of the following options:

  • Using the command-line utility
  • Using a third party plugin, in which case you must declare the plugin in the build file.

For more information, refer to sqlj - SQLJ translator.

If the value of connection_type is set to JDBC, then .java files are listed in the tree view.

Switching between SQLJ and JDBC databases

The wcaz-transform.yaml file is specific to each project, and should only be set once for the entire project. For example, if you are transforming multiple programs in your VS Code project, you should not change the database connectivity setting between these programs.

Although, you can switch between the SQLJ and JDBC databases while working on different projects. To change the database connectivity, open the wcaz-transform.yaml settings file and modify the database connectivity value to either SQLJ or JDBC.

Note: After updating the database connectivity setting, you must refresh the view by clicking Refresh on the UI.

If you switch the database connectivity in between class generation and method generation, then the following Database conflict error message is displayed: This method uses a different database connection than your existing Java classes. This can lead to incompatible generated Java. Restart transformation process using the preferred database connection set in wcaz-transform.yaml.

Similarly, if you switch the database connectivity while transforming COBOL programs within a project, then the following Database conflict error message is displayed: This code transformation uses a different database connection than previously transformed code. This can lead to incompatible generated Java. Restart transformation process using consistent database connectivity or move this code transformation to a new project.

Request an API key

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