Prerequisites for Transforming COBOL to Java

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.