Transforming COBOL to Java by using generative AI

To get started with transforming COBOL to Java code, you need to set up your VS Code workspace with the right content structure. At the least, you need a workspace with the following folders setup:

• A folder with the COBOL programs that were prepared for watsonx Code Assistant.

• A folder in which you store your generated Java code.

The content structure can be organized in many ways that depend on your development approach. For VS Code and Z Open Editor, the folder locations are key and you are prompted for them throughout the transformation workflow.

You can organize everything in a single workspace by using different folders. This entire workspace can be managed as a single repository that stores the COBOL programs to be transformed and the transformed Java. The following structure is an example layout:

- COBOL
  - SERVICES
    - PROG1.cbl
  - COPYBOOKS
    - CPYBOOK1.cpy
    - CPYBOOK2.cpy
- zapp.yaml
- Java
  - MyJavaProject1
    - bin
    - src
      - main
        - java
          - com
            - mycompany
              - datamodel
                - EntityClass1.java
                - EntityClass2.java
              - implementation
                - Program1.java
    - build.gradle

The previous layout shows two high-level folders for COBOL and Java content, plus a zapp.yaml file, which is required for the editor to parse the COBOL code correctly. It defines where the program is able to find copybooks. Z Open Editor auto-generates this file if you do not create it yourself.

The Java folder contains the generated Java code. In the previous example, it is assumed that you are using Gradle for building your Java code. However, Gradle is not a requirement. Watsonx Code Assistant for Z does not assume and generate any supporting files such as for Gradle. It is up to you to configure your Java project with the technology that you prefer.

If you are using Maven or another build system, the folders and files look slightly different, but that is for the Java developer to prepare upfront. You need to prepare the Java project with a folder structure and a dependency and build management setup before using watsonx Code Assistant. This is important as you need to ensure that the Java class path is configured so that the VS Code Java editor is able to parse the generated code and offer important refactoring operations. In the previous example, this is done by the build.gradle file. Some of these operations can be Organize Imports in-between transformation steps, or you can end up with code that contains many errors. The next section will provide you with some examples for how to do that.

When you generate your first set of Java files, watsonx Code Assistant prompts you for a folder location to generate the files in. In the previous example, you would select the Java/MyJavaProject1/src/main/java folder. When watsonx Code Assistant generates code, it creates folders on the file system for the Java packages beneath that selected folder (if they do not exist yet) and place the generated Java class files inside.

Instead of managing all your files in one folder structure, you can also separate them into multiple folders and store them in separate SCM repositories, separating your Java from the COBOL source code. To do so, you can use the VS Code's multi-root workspace feature that manages multiple folders without needing a common root folder while each folder has its own repository. You would start by opening your COBOL files into a VS Code workspace and then by using the "File" > "Add Folder to Workspace..." menu to add or create your Java project.

The structure of each folder and repository can look similar to the previous example, which is separated into different repositories and the steps of generating code would still be the same: providing folder locations and package names in the Java project.

When you use a source control system such as Git to share your repositories it is important that you also share the .code-workspace file, because watsonx Code Assistant requires that all workspaces are loaded in the same relative location from one another. In other words, the COBOL and Java workspaces must be in the same relative location for every developer that works with them as the Code Assistant stores the mapping from COBOL to Java with relative file locations. You find these mapping files in the .wcaz folders present in each workspace. These folders then also need to be shared in the same way in your Git repositories.

Code that is generated by watsonx Code Assistant references popular Java libraries for z/OS® programming such as Java Batch Launcher and Toolkit for z/OS (JZOS) and the IBM CICS® TS EXEC Utility Library for Java. IDEs such as VS Code may require some additional configuration to resolve the libraries. The actions you have to take depend on the build tool and IDE that you’re using.

Even though z/OS specific APIs do not run on the development workstation, you need to provide the libraries for the editor to build the program and provide you with correct syntax errors, code completion support, and other functions. For some of these dependencies, such as JZOS, IBM provides a pure interfaced-based library that does not contain the actual z/OS specific implementation, but only the interfaces required for editor support. Therefore, you need to configure building and deploying your application to use the real library on z/OS itself. The library is already part of the z/OS Java 11/17 runtime distribution itself and no additional library dependency is required there for JZOS.

In the example of the previous section, we showed you a folder structure with a Gradle build file. Such files can be used to define dependencies, such as JZOS, and retrieve them automatically from a repository such as Maven Central. The following is an example Gradle file. In the example, you see additional dependencies listed that you want to use for watsonx Code Assistant such as for CICS and Db2®.

repositories {
    mavenCentral()
}

dependencies {
    // Java Batch Launcher and Toolkit for z/OS (JZOS)
    compileOnly 'com.ibm.jzos:ibm.jzos:3.1.3.1'
    // JCICS, the Java API for CICS Transaction Server
    compileOnly 'com.ibm.cics:com.ibm.cics.server:2.000.0-6.1'
    implementation 'com.ibm.cics:cics-exec-utils:1.0.0'
    // IBM Data Server Driver for JDBC and SQLJ (Type 4)
    implementation 'com.ibm.db2:jcc:11.5.8.0'
    implementation 'com.ibm.db2:db2jcc_license_cisuz:4.12.55'
    // IBM Decimal Arithmetic Library for Java
    implementation 'com.ibm.jzos:decimal-arithmetic:1.0.0'
}

If you are working with Maven instead of Gradle, then dependencies would be referenced in the Maven POM files in the respective format, such as the following:

<dependency>
  <groupId>com.ibm.jzos</groupId>
  <artifactId>ibm.jzos</artifactId>
  <version>3.1.3.1</version>
  <scope>provided</scope>
</dependency>
<dependency>
  <groupId>com.ibm.cics</groupId>
  <artifactId>com.ibm.cics.server</artifactId>
  <version>2.000.0-6.1</version>
  <scope>provided</scope>
</dependency>
<dependency>
  <groupId>com.ibm.cics</groupId>
  <artifactId>cics-exec-utils</artifactId>
  <version>1.0.0</version>
</dependency>
<dependency>
  <groupId>com.ibm.jzos</groupId>
  <artifactId>decimal-arithmetic</artifactId>
  <version>1.0.0</version>
</dependency>

The JZOS (com.ibm.jzos) and JCICS (com.ibm.cics.server) libraries are provided at runtime on z/OS.  You'll need to supply them at compile-time, but don't need to deploy them with your application. When configuring these dependencies, you should use the provided scope in Maven, or add them to the compileOnly configuration in Gradle. The other dependencies (e.g. cics-exec-utils) are not provided at runtime, and should be supplied with your application when it is deployed. When you configure these dependencies, you should use the default scope (i.e. compile) in Maven, or add them to the implementation configuration in Gradle.

If in Preparing your development workspace, you cloned and imported an SCM repository or compressed file with the prepared COBOL code, you can now add COBOL programs from this repository to the watsonx Code Assistant view.

If you have a COBOL service that was exported from Refactoring Assistant as a compressed file, then you can click the Import COBOL program icon in the watsonx Code Assistant view (folder icon) and select that compressed file to import it into your first workspace by using a dialog.

All the programs that you select for transformation need to be added to the transformation services in the Cloud first. Check with your COBOL developers for the names of programs that you can transform.

To add a COBOL program from your workspace that you want to convert to the watsonx Code Assistant view, right-click the program in the File Explorer view, and select "watsonx Code Assistant for Z" > "Select COBOL for transformation". Alternatively, click the Import COBOL program icon in the Code Assistant view (folder icon, the same for importing a compressed file) and select the program from your workspace directory.

If you are upgrading from Z Open Editor v3.3, the COBOL-to-Java mapping data structures are changed from a mapping that organizes COBOL identifiers to Java identifiers to the opposite of Java to COBOL identifiers. Therefore, it is not possible to continue the mapping of a COBOL program started with v3.3 in a newer version. Finish the mapping process and generation of methods with the Z Open Editor version that you started with. After that program is transformed, you can upgrade the editor to the new version and use it to generate classes and methods for a new program. If you try generating methods with a newer version in a workspace and Java classes that were previously generated with v3.3, you see the following error message: "Java class your-class-file-name does not correspond to any COBOL program. Perform Generate Java Classes again." As the error message indicates, the only way to resolve the problem is to regenerate all the Java Classes again. That regeneration overrides any existing method transformations that you previously completed. IBM recommends that you regenerate classes into a different folder, then manually merge the older code into this new folder.

To start generating Java classes from the COBOL program, follow these steps.

1. Either right-click the COBOL file entry in the watsonx Code Assistant for Z view or click the icon next to it to run the command "Generate Java Classes".

2. Select either "Browse for directory" or "Input absolute path" in the drop-down dialog to either go to the folder with a dialog or by typing the absolute folder path. For more information about details on the folder to select, see Preparing your development workspace.

3. Review the suggested names for the packages, classes, methods, and variable names in the "Review Java class design" view. The COBOL names are shown right next to them for comparison. Use the caret icons next to names to expand sections such as classes to see their members. You can edit any of the names as required.

4. Click one of the buttons at the end of the view to perform one of the following actions:

   1. "Save" to store the current mappings to local storage so you can come back later and finish the mapping work.

   2. "Generate Java Classes" to create the Java files.

A VS Code notification appears when generation is completed.

If you later open this view a second time to make more changes and resubmit, you need to consider that all classes are regenerated overwriting the existing ones, which include any methods that are generated and edits that are made. A dialog prompts you to confirm that you intend to overwrite all code.

After Java classes were generated, you can open them in the editor and generate method content one by one.

1. After generating the Java classes, the watsonx Code Assistant tree view shows new child nodes beneath the COBOL program name. Expand the node to see a list of Java classes that contain methods that can be transformed by using watsonx Code Assistant AI features.

2. Expand any Java classes to see the list of methods and select one to open it in a Java editor tab.

3. The first time that you open a Java file in VS Code you need to wait for the Java development tools to initialize.

   • A new view called "Java Projects" opens and is populated with the Java package and files that were generated.

   • Sometimes the Java tools can get stuck during initialization. For more information about how to resolve these issues, see Troubleshooting.

4. To generate the method, you can either click the icon in the watsonx Code Assistant tree view next to the method name or right-click within the Java editor the method name to open the context menu and select "IBM watsonx Code Assistant for Z" > "Generate Java Method".

5. Review the generated Java code in the "Java Methods" code preview view.

6. You can optionally click the name of the COBOL program file in the view to open and compare with the code that you are converting from.

7. Click Insert to add the generated method code to the Java class.

8. Right-click in the Java editor and select "Format Document".

9. Use the Java development tools to fix any missing imports by clicking the red squiggles of any error you see in the editor and clicking the yellow code action light bulb. A menu is opened with the "Import <class>" or "Add all missing imports" action to fix the issue if you provided the respective dependencies for your project as described in Preparing your development workspace.

10. Rate your experience by clicking Like / Dislike. IBM does not receive any code through this function, only the rating.

When you complete generating code for a Java class, you can refactor the file by moving it into another package location.