Transforming COBOL to Java using generative AI

Preparing your development workspace

To begin with transforming COBOL to Java code, you must set up your VS Code workspace with the appropriate content structure. At the minimum, 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 the generated Java code.

The content structure can be organized in multiple formats depending 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 displays two high-level folders for COBOL and Java content, and a zapp.yaml file, which is required for the editor to parse the COBOL code correctly. It defines where the program can find copybooks. Z Open Editor auto-generates this file if you do not create it manually.

The Java folder contains the generated Java code. In the previous example, it is presumed that you are using Gradle for building your Java code. However, Gradle is not a requirement. watsonx Code Assistant for Z does not presume and generate any supporting files such as for Gradle. You to configure your Java project with the technology as per your requirement.

If you are using Maven or another build system, the folders and files look slightly different, but that is for the Java developers. You must organize the Java project with a folder structure and a dependency and build management setup before using watsonx Code Assistant. This is important as you must ensure that the Java class path is configured so that the VS Code Java editor is able to parse the generated code and provide the critical refactoring operations. In the earlier example, the build.gradle file performs this task. Certain operations, such as Organizing Imports, can occur during intermediary transformation steps. Without careful handling, this may lead to code filled with numerous errors. The upcoming section offers examples to guide you on how to approach this effectively.

When you generate the first set of Java files, watsonx Code Assistant prompts for a folder location to generate the files. In the earlier example, you can select the Java/MyJavaProject1/src/main/java folder. When watsonx Code Assistant generates code, it saves the Java packages in the previously created folders. If folders are not created, then it creates new folders within the selected folder to save the Java packages.

Advanced development workspace setup: Multi-root workspace that separates COBOL and Java code

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 proceed, you can use the VS Code's multi-root workspace feature that manages multiple folders without a common root folder while each folder has its own repository. To begin, open the COBOL files into a VS Code workspace and then use the File > Add Folder to Workspace... menu to add or create the Java project.

The structure of each folder and repository can look similar to the previous example, which is separated into different repositories. The step to generate code remains 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 all workspaces that are loaded in the same relative location from one another. The COBOL and Java workspaces must be in the same relative location for every developer that works with them as the Z Code Assistant stores the mapping from COBOL to Java with relative file locations. You can locate these mapping files in the .wca4z folders present in each workspace. These folders must be shared in the same approach in your Git repositories.

Providing Java dependencies

Code that is generated by watsonx Code Assistant references 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 requires some additional configuration to resolve the libraries. The actions that you must take depend on the build tool and IDE that is available in your system.

Although z/OS specific APIs do not run on the development workstation, you must provide the libraries for the editor to build the program and provide you with correct syntax errors, code completion support, and other functionalities. For some of these dependencies, such as JZOS, IBM provides an interfaced-based library that does not contain the actual z/OS specific implementation, but only the interfaces required for editor support. Therefore, you must configure building and deploying your application to use the library on z/OS. The library is part of the z/OS Java 11/17 runtime distribution and no additional library dependency is required 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 can see additional dependencies listed that you can 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:

<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®.  Supply them at compile time, but do not deploy them with your application. When you configure these dependencies, you must use the provided scope in Maven, or add them to the compileOnly configuration in Gradle. The other dependencies (for example cics-exec-utils) are not provided at run time, and must be supplied with your application when it is deployed. When you configure these dependencies, you must use the default scope (that is, compile) in Maven, or add them to the implementation configuration in Gradle.

Importing files into the Z Code Assistant view

If you have cloned and imported an SCM repository or compressed file with the prepared COBOL code in Preparing your development workspace, then you can 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 the compressed file to import it into the first workspace.

All the programs that you select for transformation must be added to the transformation services in the Cloud. Verify with your COBOL developers for the programs that you can transform.

To add a COBOL program from your workspace 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 Z Code Assistant view (folder icon, the same for importing a compressed file) and select the program from your workspace directory.

Upgrading Z Open Editor from an earlier version

Java class your-class-file-name does not correspond to any COBOL program. Perform Generate Java Classes again.

Selecting COBOL for transformation

Run the following steps to select COBOL within the procedure division for transformation:

1. Right-click and select Select COBOL for transformation from the watsonx Code Assistant for Z menu.

   An information message appears indicating that the application is checking for existing metadata in watsonx Code Assistant for Z for the selected services.

2. The COBOL selections are listed in the IBM WATSONX CODE ASSISTANT FOR Z view.

Transforming selected COBOL

Run the following steps to transform the COBOL selection within the procedure division:

1. Right-click on the COBOL selection and click Transform to Java in the watsonx Code Assistant for Z menu.

   The transformed Java logic is displayed in the Code transformation view. This web view is not editable.

2. Use the Copy Java option in the Code transformation view to copy the transformed Java logic.
3. Browse to the modernization Java project and paste the copied logic. You can edit the Java logic in this view.

Initial step for class and method generation

Perform the following steps to transform COBOL programs into Java by using the Guided or Bulk generation approaches:

1. Click the icon next to the COBOL file entry to run the Transform to Java command. Alternately, right-click on the COBOL file and select Generate Java classes from the menu.

   The Generated Java classes window appears.

2. Use the Browse for directory or Input absolute path options to specify a location to save the generated Java files.

3. The Java class design tab appears listing suggested Java classes for the selected COBOL program.

   This initial set of Java classes includes a main class and one or more data classes.

   For each Java component, the table provides the following information:

   • Java name: Name of the Java component.
   • Java type: Data type of the Java class, method, or variable.
   • COBOL name: Name of the corresponding COBOL variable or constant.
   • COBOL type: Data types used to define the COBOL variable or constant.

   You can perform the following actions on the components of this table:

   • Expand a Java class entry to view the included Java methods and variables.

   • Use the Search icon to search this table for a specific Java or COBOL component.

   • Use the Filter icon to filter this table based on Java or COBOL types.

     Use the check boxes to filter the list based on one or more Java or COBOL types, or a combination of Java and COBOL types.

   • Click the Java name field to edit it. You can edit the Java names at this stage or wait for the transformation to be completed.

     Note: The Java name field cannot be empty as Java classes cannot generated with empty Java names. If this field is empty, an error message is displayed.

4. Select Guided or Bulk and click Generate Java classes.

   • Guided: In this approach, you can gradually generate Java classes and methods. This approach creates dependent data classes and adds stub methods to the main class. Repeat this process for all stub methods. This approach facilitates easier understanding of the transformed Java program.

     The Guided approach creates a single main Java class and one or more data classes in the initial step. The main class contains the business logic from the COBOL program. It includes an initial stub method that represents the control flow of the program. The data classes include data structure from the selected COBOL program. This allows for easy understanding of the Java classes. You can generate additional Java classes based on your requirement.

   • Bulk: In this approach, all Java classes and methods are generated at once. While this approach may be time effective, it is difficult to understand the relationship between the various methods and classes generated, or to fix errors.

Stub methods are created initially when Java classes are generated using Guided or Bulk approach. Each stub method is preceded by an icon that reflects its status. The following table provides more information about the icons and their significance.

Icons	Description
	A grey box icon with a slash indicates that the Java method stub not yet added to the main class.
	A purple box icon indicates that the Java method stub is added to the main class. You can proceed to generate Java methods for stubs preceded by this icon.
	The grey progress icon indicates that Java method generation is in progress.
	A purple box with a tick mark indicates that Java method is generated for this stub.

Generating Java methods for the initial Java classes using Guided approach

If you selected the Guided option in Step 4, then the initial Java classes are created and listed in the watsonx Code Assistant for Z view.

Each initial class contains a set of stub methods. Observe that only the required stub methods are added to the initial class. All other stub methods are disabled.

Perform the following steps to generate Java methods for the stub methods.

1. Expand a Java class and click the Generate Java method icon next to the stub method.

2. The Code transformation window appears to display the progress of method generation.

3. After the Java method generation, the Code transformation window displays the following tabs:

   • Method generation tab displaying the newly generated method. This tab provides the following information about the method:

     Name of the Java stub method.

     Name of the COBOL file from which this Java class is generated in the initial step.

     Name of the COBOL paragraph for which this method is generated.

   • Dependent classes tab lists the Java classes for the generated method.

   Use the Insert option in the Code transformation window to copy the generated Java code to the previously selected Java stub file in the watsonx Code Assistant for Z view.

   Observe that the icon has changed for this stub file. Some of the stub files that were previously disabled are now added to the initial class. Repeat this process for all the Java stub files.

   Note: You cannot edit the Java code in the Code transformation window. However, you can edit the code after inserting it into the watsonx Code Assistant for Z stub file.

Generating Java methods using Bulk approach

If you selected the Bulk option in Step 4, then the application generates all required Java classes and methods for the selected COBOL program. A message box appears, indicating the progress of method generation. You can click Cancel on the message box at any time during the generation process. Although the application stops creating new methods, it completes generating any methods that are already in progress.

Compared to the Guided approach, Bulk class generation takes longer as all Java classes and methods are generated at once.

You can view a list of all generated Java files in the watsonx Code Assistant for Z view. Observe that the icon preceding the Java files indicate that method generation is completed.