Transforming COBOL to Java by using generative AI
Transform COBOL services to Java™ by using an AI-assisted approach with IBM® watsonx Code Assistant™ for Z and IBM Z® Open Editor.
Preparing your development workspace
To get started with transforming COBOL to Java code, you need to set up your VS Code workspace with the correct 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.
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 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. 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 are still 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.
Providing Java dependencies
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 that 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 need to supply them at compile time, but don't need to deploy them with your application. When you configure these dependencies, you should 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 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.
Importing files into the Code Assistant view
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.
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.
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. Generating Java classes
To start generating Java classes from the COBOL program, follow these steps.
-
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.
-
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.
-
Review the suggested names for the packages, classes, methods, parameter names, local, and global 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.
Note: There is a possibility that you get a read-only table where you cannot edit the java package, class, method, or variable name. This is due to a change in the watsonx Code Assistant for Z server, which makes the previously generated Java class design in the project outdated. For more information on how to regenerate the java classes or continue with the existing java class structure, see Error: Class Mapping Command Utilities error handler. -
Click one of the buttons at the end of the view to perform one of the following actions:
-
Click Save to store the current mappings to local storage so you can come back later and finish the mapping work.
-
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.
Generating Java methods
After Java classes were generated, you can open them in the editor and generate method content one by one.
-
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.
-
Expand any Java classes to see the list of methods and select one to open it in a Java editor tab.
-
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.
-
-
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.
-
Review the generated Java code in the Java Methods code preview view.
-
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.
-
Click Insert to add the generated method code to the Java class.
-
Right-click in the Java editor and select Format Document.
-
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.
-
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.