watsonx Code Assistant for Z Workshop¶

Agenda for November 14, 2024 workshop¶

Activity	Time
Presentation and Demonstration	11:00 pm - noon US EST
Hands-on, self-paced lab	noon - 5:00 pm US EST

Presentation¶

Presentation

Lab¶

Start here with the Lab Overview.

Workshop Environment Architecture¶

Please visit this page to see the architecture of the workshop's lab environment.

Workshop Owners¶

Acknowledgement¶

Thank you to Ashish Sahoo of IBM Consulting whose hard work maintaining the watsonx Code Assistant for Z zVA image and documenting a watsonx Code Assistant for Z workflow for this image formed the foundation for our lab.

Presentations ↵

Ended: Presentations

Workshop Architecture Diagram¶

workshop-arch

Lab Assignments¶

Each student has their own lab systems. Please ensure you use only your own systems.

The TechZone lab URL is used to access the Code Explanation section of the lab. You will be prompted for a password- this password will either be in the TechZone lab access column in the table, or it will be provided by the instructors by some other means. You have been assigned a lab environment based on the email address you provided when registering for the class. You must have an IBM ID associated with that email address. If you do not have an IBM ID associated with that email address, you have two choices- 1) let the instructors know what email address is associated with your existing IBM ID and they will update the system, or 2) create an IBM ID with the email address you used to register for the class. If you do not have and do not wish to create or cannot create an IBM ID, you can still do the other sections of the lab as instructed in the next paragraph.

The remaining sections of the lab- the Understand, Refactor, Transform and Validate phases- are performed on a zVA instance.
When you click on your unique zVA lab URL you will be presented with a new browser tab and a sign-in screen. Enter Administrator as the userid. The password will be either listed in the table below in the Administrator password column or it will be distributed to you under separate cover.

CODE EXPLANATION LAB ##¶

All students should use this URL: https://techzone.ibm.com/my/workshops/student/6736438be6fdd169e50e8722

Name	TechZone lab URL	TechZone lab password	zVA lab URL	Administrator password
Alexandre O.	https://techzone.ibm.com/my/workshops/student/6736438be6fdd169e50e8722	`ocdU7W6vgYaZbTS`	http://ibm.biz/wscwca4z01	`fY8gbVPqhQn8`
Brian O.	https://techzone.ibm.com/my/workshops/student/6736438be6fdd169e50e8722	`ocdU7W6vgYaZbTS`	http://ibm.biz/wscwca4z02	`jzFFytUUr3xh`
Christopher O.	https://techzone.ibm.com/my/workshops/student/6736438be6fdd169e50e8722e	`ocdU7W6vgYaZbTS`	http://ibm.biz/wscwca4z03	`zrsFYbhA5wLG`
Dusty R.	https://techzone.ibm.com/my/workshops/student/6736438be6fdd169e50e8722	`ocdU7W6vgYaZbTS`	http://ibm.biz/wscwca4z04	`zGdPDgbevgX6`
Eric S.	https://techzone.ibm.com/my/workshops/student/6736438be6fdd169e50e8722	`ocdU7W6vgYaZbTS`	http://ibm.biz/wscwca4z05	`vJKBb6EcCKjE`
Gianni L.	https://techzone.ibm.com/my/workshops/student/6736438be6fdd169e50e8722	`ocdU7W6vgYaZbTS`	http://ibm.biz/wscwca4z06	`fPzR8pt6nphx`
Hari Y.	https://techzone.ibm.com/my/workshops/student/6736438be6fdd169e50e8722	`ocdU7W6vgYaZbTS`	http://ibm.biz/wscwca4z07	`vhXecqcX5mAD`
Jacques T.	https://techzone.ibm.com/my/workshops/student/6736438be6fdd169e50e8722	`ocdU7W6vgYaZbTS`	http://ibm.biz/wscwca4z08	`tV64UNAKuZZp`
Joseph C.	https://techzone.ibm.com/my/workshops/student/6736438be6fdd169e50e8722	`ocdU7W6vgYaZbTS`	http://ibm.biz/wscwca4z09	`ntTJZaV5mYgC`
Joshua C.	https://techzone.ibm.com/my/workshops/student/6736438be6fdd169e50e8722	`ocdU7W6vgYaZbTS`	http://ibm.biz/wscwca4z10	`lXrFrTL7WJMR`
Karoline P.	https://techzone.ibm.com/my/workshops/student/6736438be6fdd169e50e8722	`ocdU7W6vgYaZbTS`	http://ibm.biz/wscwca4z11	`vSRfnk7zew7r`
Lance Z.	https://techzone.ibm.com/my/workshops/student/6736438be6fdd169e50e8722	`ocdU7W6vgYaZbTS`	http://ibm.biz/wscwca4z12	`wECeYDd5Marg`
Matthew H.	https://techzone.ibm.com/my/workshops/student/6736438be6fdd169e50e8722	`ocdU7W6vgYaZbTS`	http://ibm.biz/wscwca4z13	`yzJRkd9rbnGE`
Matthew S.	https://techzone.ibm.com/my/workshops/student/6736438be6fdd169e50e8722	`ocdU7W6vgYaZbTS`	http://ibm.biz/wscwca4z14	`h3EdU2Vw5FLr`
Patricia B.	https://techzone.ibm.com/my/workshops/student/6736438be6fdd169e50e8722	`ocdU7W6vgYaZbTS`	http://ibm.biz/wscwca4z15	`aJm7qXWmZKk3`
Raghu C.	hhttps://techzone.ibm.com/my/workshops/student/6736438be6fdd169e50e8722	`ocdU7W6vgYaZbTS`	http://ibm.biz/wscwca4z16	`tYm54tapkB2G`
Ramesh M.	https://techzone.ibm.com/my/workshops/student/6736438be6fdd169e50e8722	`ocdU7W6vgYaZbTS`	http://ibm.biz/wscwca4z17	`yYmejnEZG4P3`
Roberto I.	https://techzone.ibm.com/my/workshops/student/6736438be6fdd169e50e8722	`ocdU7W6vgYaZbTS`	http://ibm.biz/wscwca4z18	`f78DqAEmH7bt`
Ryan M.	https://techzone.ibm.com/my/workshops/student/6736438be6fdd169e50e8722	`ocdU7W6vgYaZbTS`	http://ibm.biz/wscwca4z19	`dzVuMlLnAy99`
Shoaib A.	https://techzone.ibm.com/my/workshops/student/6736438be6fdd169e50e8722	`ocdU7W6vgYaZbTS`	http://ibm.biz/wscwca4z20	`kYQjvnYk456K`
Skip W.	https://techzone.ibm.com/my/workshops/student/6736438be6fdd169e50e8722	`ocdU7W6vgYaZbTS`	http://ibm.biz/wscwca4z21	`e7Ty699Gka7x`
Swapna K.	https://techzone.ibm.com/my/workshops/student/6736438be6fdd169e50e8722	`ocdU7W6vgYaZbTS`	http://ibm.biz/wscwca4z22	`pSHx6kFDntSr`
Todd Z.	hhttps://techzone.ibm.com/my/workshops/student/6736438be6fdd169e50e8722	`ocdU7W6vgYaZbTS`	http://ibm.biz/wscwca4z23	`ktakhF7kGLXJ`
Victor R.	https://techzone.ibm.com/my/workshops/student/6736438be6fdd169e50e8722	`ocdU7W6vgYaZbTS`	http://ibm.biz/wscwca4z24	`yZLEKSnMcge2`
Vincent T.	https://techzone.ibm.com/my/workshops/student/6736438be6fdd169e50e8722	`ocdU7W6vgYaZbTS`	http://ibm.biz/wscwca4z25	`dxc7FSA4p986`
Viswasarathy R.	https://techzone.ibm.com/my/workshops/student/6736438be6fdd169e50e8722	`ocdU7W6vgYaZbTS`	http://ibm.biz/wscwca4z26	`tdL6au54JCH6`
Victoria P.	https://techzone.ibm.com/my/workshops/student/6736438be6fdd169e50e8722	`ocdU7W6vgYaZbTS`	http://ibm.biz/wscwca4z27	`ae7suxBlaNgu`
Lucas T.	https://techzone.ibm.com/my/workshops/student/6736438be6fdd169e50e8722	`ocdU7W6vgYaZbTS`	http://ibm.biz/wscwca4z28e	`nh3X92zPcTgA`
TBD	https://techzone.ibm.com/my/workshops/student/6736438be6fdd169e50e8722	`ocdU7W6vgYaZbTS`	http://ibm.biz/wscwca4z29	`N/A`
TBD	https://techzone.ibm.com/my/workshops/student/6736438be6fdd169e50e8722	`ocdU7W6vgYaZbTS`	http://ibm.biz/wscwca4z30	`N/A`

Lab Documentation ↵

Lab 1 - Code Explanation ↵

Code Explanation¶

Overview of the Code Explanation Phase¶

The purpose of the Code Explanation phase is to understand your code. You may need to do that for a number of reasons such as learning, troubleshooting, documentation, testing, maintenance, and modernization. This capability takes advantage of generative AI based on IBM's Granite foundation model in order to explain in natural language what your code is doing, whether it's COBOL or JCL.

In order to generate explanations, all you need to do is highlight the area of code for which you want to generate an explanation, right click, and select a simple, detailed, or guided explanation type (for COBOL) or a simple or detailed explanation type (for JCL).

Simple: A simple summary explanation provides the business purpose and a high-level summary of code function.
Detailed: A detailed explanation provides the business purpose, the inputs, outputs, and key data records, as well as a detailed functional summary of code function.
Guided: A guided explanation provides the business purpose and a step-by-step description of the code function.

Connecting to the watsonx Code Assistant for Z LLM¶

Code explanations are generated by the watsonx Code Assistant for Z LLM running in IBM Cloud. In order to connect your lab environment to the LLM, you will need to enter an API key into your Visual Studio Code instance. This API key will be provided by your lab instructor.

Log in to your TechZone lab environment. You can find connection details on the Lab Assignments page.
On your TechZone lab environment's desktop, find the Git bash icon and double-click it in order to open up a terminal window:
Optional: By default, the font size in the terminal window you just opened is rather small. If you would like to increase it, click on the icon in the upper left corner of the window, choose Options... and then Text and you will be able to modify the font size to your liking. Click the Save button to apply the changes you make, or click the Cancel button if you change your mind and want to keep the settings as you found them. The next few instructions will show screen snippets after the font size was doubled from 9 pt to 18 pt.
In your terminal window, enter the following command, which will download a GitHub repository owned and maintained by Garrett Woodworth, one of our instructors:

git clone --recurse-submodules https://github.com/siler23/wca4z-pilot-shortcut

This repository contains, among other things, COBOL programs that you can use for trying out the Code Explanation feature for COBOL. The --recurse-submodules option to the git clone command brings down another repository, github.com/ibm/zopeneditor-sample, that Garrett has linked to from his repository, and that you will use in the next section when exploring the Code Explanation feature for JCL.

The screen snippet below shows the command and its expected output:
Enter the following command which changes into the top-level directory of the repository you just downloaded and then lists this directory.

cd wca4z-pilot-shortcut && ls

The screen snippet shows the command and its expected output:
Enter the folowing command into your terminal window:

code . && exit

This command will open up Visual Studio Code (VS Code) within your current directory (the . in code . means "use the current directory"), which is the top-level directory of your clone, and if this is successful it will close your terminal window. (The && is a logical AND so it only executes the following exit if VS Code opens successfully). The Git bash terminal window is not needed for the rest of the lab but if you wish to keep it open, just omit the && exit.
Click the blue button labeled Yes, I trust the authors.

Note: You must choose this in order for the watsonx Code Assistant for Z VS Code extensions to work properly.
At the bottom Explorer pane on the left, expand the IBM WATSONX CODE ASSISTANT FOR Z section if it is not already expanded.

You should see a prompt to Enter API key.
On your workstation, i.e., not within your lab system, copy the instructor-provided API key into your workstation's clipboard using Ctrl-C. The instructor will give you directions on where to find this key.
Back within your lab system, click the Enter API key prompt. A notification box may open in the lower right (not shown in screen snippet) asking you to confirm that you want to create a new authentication session for IBM watsonx Code Assistant for Z. Click Yes. An input bar will appear in the top-middle of the page. Paste the instructor-provided API key from your workstation clipboard with Ctrl-V and press Enter.

If this was successful, the Enter API key prompt should disappear and you should see a message popup in the lower right that says Successfully connected to watsonx platform authenticator.

Code Explanation for COBOL¶

Note: You may see some minor differences in the screen snippets in this section from what you will see on your system. For example, in the screenshots the CLIENTCOBOL folder appears in all uppercase, while on your system it may appear as clientCobol. Any differences you notice should not affect your ability to complete the lab with these instructions. Please don't hesitate to ask your instructor for help!

In the top of the Explorer pane on the left, expand the clientCobol folder and then the cobol folder underneath that, if it they are not already expanded. You will see a selection of COBOL programs that end with .cbl.
Left-click on the file named LGACDB01.cbl to open it in the editor window.

Note: The first time you do this, you may receive a popup notification in the lower right about the creation of a ZAPP file. You may close this window or allow it to disappear on its own. An output area with messages may also appear and take up much of your VS Code screen. You can reduce the size of the message area or hide it completely. See the below screen snippet for hints:

Scroll down to line 232 in the code which contains the string INSERT CUSTOMER.
Highlight the INSERT CUSTOMER paragraph which is lines 232 through 304 of LGACDB01.cbl

Tip: Rather than clicking and dragging your cursor, it may be easier to highlight all of line 232, then holding your SHIFT and Down Arrow keys.
Right-click on the highlighted lines, hover over the "watsonx Code Assistant for Z" option, and select "Generate Simple Explanation".

A new tab will open on the right side of the screen with the generated explanation. Feel free to peruse the explanation returned from the LLM. Note that the explanations returned may differ from the explanations shown in the screen snippets in this lab because of updates to the LLM, and also just because of the non-deterministic nature of Generative AI output.
Repeat the previous step to generate Detailed and Guided explanations of the same COBOL paragraph. You will observe that each time you request an explanation, a new tab opens up on the right side of the screen. You may want to close out previous explanations to reduce the clutter on your screen.

You should notice an increase in the level of detail in the Detailed and Guided explanations compared to the Simple explanation.

Code Explanation provides the ability to regenerate the explanation, download it, insert it into the COBOL code as a comment, or copy it.
Feel free to ask for explanations against some of the other programs within this folder, and then continue on in the lab to try Code Explanation with JCL.

Code Explanation for JCL¶

In the top of the Explorer pane on the left, expand the JCL folder within the zopeneditor-sample folder. See the screen snippet below for guidance. You should see some files ending in .jcl. (There are more files in this folder than are shown in the screen snippet.)
Left-click on the ALLOCATE.JCL file in the JCL folder. In a moment, the OUTLINE section in the Explorer view will contain information about the JCL. You may need to expand the OUTLINE section or collapse other sections to make room to see the type of information shown in the screen snippet- the job name, step names, and DD statements from the JCL. This screen snippet shows the DELETE step that calls the IEFBR14 program, and a few of the DD statements are shown:
Now, doubld-click on the DELETE step in the outline. This will highlight the entire step. The screen snippet below shows the highlighting of the step after you double-clicked on it. (Not all of the step is shown in the screen snippet.)
Right-click within the highlighted JCL, choose watsonx Code Assistant for Z, then Generate Simple Explanation, as shown here:

A tab will open on the right, and you will receive an explanation for the JCL, similar to what is shown below:
You should be familiar enough with the process now to get a detailed explanation on this step or other steps in this job, without the aid of screen snippets. Explore a few different JCL jobs. Note that the scope of a JCL explanation is a single job step. If you were to select an entire job, you will get a message telling you that only the first step is being sent for an explanation. You can also select just a small part of a step, and the entire step containing the selected text will be explained. Try out enough explanations to convince yourself that these preceding statements about the behavior of Code Explanation for JCL are indeed true!

Code Explanation Lab Summary¶

In the Code Explanation phase,

We learned more about what the INSERT CUSTOMER paragraph is doing in the LGACDB01 COBOL program.
We created simple, detailed, and guided explanations of a COBOL paragraph.
We learned how to insert these explanations into the code as comments or download them for external use.
We learned how to get explanations for a JCL job step.

This completes the Code Explanation lab.

Ended: Lab 1 - Code Explanation

Lab 2 - Understand, Refactor, Transform, Validate ↵

Lab Overview¶

In this lab you will explore four of the phases in the IBM watsonx Code Assistant for Z workflow. The lab is performed on instructor-provided instances that you access through your web browser. You do not need any additional software on your personal laptop or workstation other than a modern web browser.

The phases you will explore are:

Understand
Refactor
Transform
Validate

Depending on your motivation for using IBM watsonx Code Assistant for Z, not all of the above phases are required. If you just need to gain a better understanding of your existing COBOL application estate, but do not wish to refactor your application into more modular business services, you might only perform the Understand phase.

If you are interested in creating modular COBOL business services but do not have an interest in Java, you will first perform the Understand phase in order to identify parts of your application to create modular services from, and then you will perform the Refactor phase in order to create these services.

If you are interested in converting parts of your COBOL application to Java, then after the Understand and Refactor phases you will perform the Transform and Validate phases.

The lab works with a sample COBOL application and gives an idea of what is involved in each phase.

In order to navigate through the lab, click the link at the bottom right of this page to start the Understand phase. Follow the instructions on each page in order, and at the bottom of each page you'll see the link to the next page in the lab.

Click the Understand Phase link at the lower right to get started!

Understand Phase¶

Overview of the Understand phase¶

During the Understand phase an application architect uses Application Discovery and Delivery Intelligence (ADDI) to analyze an application, primarily through its source code, but also often through other artifacts. The analysis performed by ADDI is stored in an ADDI Project, using a relational database schema. The application architect uses the ADDI Analyze Client to create and view charts, graphs and reports in order to help gain a better understanding of the application and identify candidates for refactoring.

Note: Even if an enterprise already has a perfect understanding of their COBOL application, the Understand phase is a prerequisite for the Refactor phase, because the components used in the Refactoring phase read an ADDI project's database.

Note: ADDI is a powerful product, with a large number of features and reports. This lab only scratches the surface of what can be done in ADDI with a realistic application. The Understand phase is a critical part of the watsonx Code Assistant for Z workflow, the importance of which is likely understated by this lab's ADDI-related instructions- in real-world usage scenarios it is to your benefit to learn more about ADDI's capabilities in order to give proper weight to the Understand phase.

Log in to your IBM Z Virtual Access (zVA) environment. Your lab environment is a Windows system that you will access via your web browser.

If you are taking this lab during an IBM Washington Systems Center-hosted workshop, then your access details for your environment are on this page. If you are not sure how to access your environment, please ask your lab instructor for help.

The picture below shows what your browser tab or window should look like after you have successfully logged in to your zVA environment.

Note: All lab instructions, unless explictly noted, are performed within your browser tab or window in which your zVA Windows environment is displayed.

Introducing GenApp¶

In this lab, you will be using the general insurance application, GenApp. GenApp is a sample CICS COBOL application that provides transactions that could be used by an insurance company to create and manage its customers and insurance policies. Could be was italicized in the previous sentence as GenApp is provided primarily for educational and testing purposes- if you are an actual insurance company it is likely that market forces would encourage you to use transactions that are slightly more sophisticated than the ones in GenApp.

You can read more about GenApp here.

Explore the application using ADDI and IBM Developer for z/OS¶

In simple terms, ADDI consists of features to build an ADDI project that contains detailed application information, and features to analyze the ADDI project that you have built. For this lab, the build process has already been performed against the GenApp project, and you will start with the analyze process, which you will perform within the IBM Developer for z/OS (IDz) product, using the Application Discovery Browser Perspective.

Open IBM Developer for z/OS (IDz) from the taskbar by single-clicking on the icon highlighted below. IDz is built on the open source Eclipse project. The ADDI Analyze Client functionality is delivered via Eclipse-based plugins, so the application architect performs analysis within IDz using functionality provided by these plugins.
After a short while you will probably see a "splash screen" for IBM Developer for z/OS. Then it will disappear and you may be prompted with the Select a directory as workspace popup window. If you receive this, leave the default workspace path unchanged and click Launch.

The default workspace path on your lab system should be:
```
C:\Users\Administrator\.zosexplorer
```
The launcher window will close, the splash screen may return for a moment, then disappear, and finally the Application Discovery Browser perspective provided by ADDI will be opened up within IDz.

IDz can take a few minutes to fully load in your lab environment. After clicking Launch, the popup window will close and it may look like the application is not opening. Please be patient- wait at least three minutes before you wake up the instructors.
Click the Explore tab in the middle of IDz, near the top. Once you see the Explore projects tab, right-click on the empty list of projects and click Get Project List.

The GenApp project will appear.
Click the GenApp project to highlight it. This will bring up a new pane on the right side of the page that shows the many charts, graphs and reports that are provided by ADDI. Information about these reports can be found in the ADDI documentation.

Double-click Program Callgraph in the new pane.
A new window will appear where you can select which programs to analyze. It may take a moment for the program names to appear in the Available programs pane within the window. Once they do, click the double arrow button to move all of the programs from Available programs to Selected programs, then click Finish.

Please be patient. This can take a minute or two to fully load.

When loaded, you will see a call graph for all programs, CICS transactions, tables, and other files in the GenApp application and the interdependencies between them.

This is an interactive graph. You can zoom in and scroll around the graph to see different objects. One way to zoom in is to click the Interactive Zoom Tool icon in the toolbar at the upper right, above the graph. Hover over the icons until you find the Interactive Zoom Tool, then click on it. Then click on the graph and very slowly drag your cursor down in order to zoom in on the graph. You can zoom out on the graph by very slowly dragging your cursor up. When you're satisfied with the readability of the objects, you can switch to the Mouse Pan tool, which is the icon that looks like a hand, and should be a couple icons to the left of the Interactive Zoom Tool icon. The Mouse Pan Tool is convenient for bringing different parts of the graph into view. You can also right-click the objects to see more specific details about them.

Note: Trying to zoom in and out on the graph in the zVA browser tab or window can be difficult- it is easy to get in a state where you wish you could start over. You can- just close the graph by clicking the x icon on its tab and then repeat step 4 and this step.
In the left side of the page, you will see a Graph Inventory. Notice that the CICS transactions, COBOL Programs, and different object types have been identified. Expand the COBOL Programs section to see the list of COBOL programs that are part of GenApp.
In the Graph Inventory, right-click the GETPAVG program, hover over Mainframe Graphs, and select Program Callgraph.
Leave the default options unchanged and click Finish.

A new callgraph will be generated that is scoped to only the objects in the application flow that are used by the GETPAVG program or by other programs that are called by GETPAVG.

Two COBOL programs should be displayed in the callgraph:
1. The main program GETPAVG. This program accesses the input and output files.
2. A called program named GETAAVG. This program accesses various SQL tables shown at the bottom of the callgraph.
Double-click on the COBOL program named GETAAVG to open a new panel at the bottom with the COBOL source code of GETAAVG. Maximize the source code by clicking the button in the top-right of the panel.

The COBOL program GETAAVG should now be maximized.

If you look through the GETAAVG source code, you will find that in the 2000-CHECK-TYPE paragraph it will perform different operations depending on the request ID (IN-REQUEST-ID data item) passed in to GETAAVG via its LINKAGE SECTION:
1. Customer Action (0AVCUS)
2. Get Average Premium (0AVMOT)
3. Get Endowment (0AVEND)
4. Get House (0AVHO)
5. Get Commercial (0AVCOM)
For the purposes of this lab, let's assume that the application architect has identified the paragraph that implements the Get Average Premium functionality as a good candidate for refactoring. (This is why we've highlighted Get Average Premium in the above list.)
Scroll down to line 342 in the COBOL code until you find the 3100-GET-AVG-MOT-PREMIUM paragraph. Pro tip: You may find that using Navigate->Go to line... from the IDz menu is a more enjoyable experience than scrolling.

Hint: You can check the line you're on using the first number pointed out in the image above- this shows the location of the current cursor position so you may need to click inside the source code after you've scrolled.

The 3100-GET-AVG-MOT-PREMIUM paragraph is one small part of the overall GenApp sample application. It is called when the request ID is 0AVMOT.

This paragraph calculates the average premiums for a customer's motor vehicle insurance policies. For this lab we are going to assume that the application architect has decided that this would be a good service to refactor into a modular business service.

In the next section of the lab, you will refactor this paragraph into a separate COBOL service, and then in the section after that, you will transform this service into Java code.

You will not be using IDz anymore in the lab instructions so you may either minimize it or exit from it altogether.

In the Understand phase,

We selected the GETPAVG program to understand its flow and related components.
We explored the called program GETAAVG and its 3100-GET-AVG-MOT-PREMIUM paragraph and decided that the functionality in this paragraph is a good candidate for refactoring into a modular COBOL service and for then transforming into Java code.

Refactor Phase¶

Overview of the Refactor phase¶

In the Refactor phase, the COBOL application developer uses the Refactoring Assistant VS Code extension to extract parts of the COBOL application into a modular business service. In the typical workflow the application architect has identified the functionality to refactor and has communicated this to the COBOL application developer. In this lab the functionality within the GenApp application that calculates a customer's average motor vehicle insurance policy premiums has been selected.

Start the Refactoring Assistant server¶

In addition to the Refactoring Assistant VS Code extension that you'll be using shortly, there is a server component to Refactoring Assistant that is delivered as an Open Container Initiative (OCI) image that runs as a container in a Linux Virtual Machine (VM). Your lab environment provides this Linux VM but you need to start the Refactoring Assistant server within the VM by following the instructions in this section.

Open PuTTY from the taskbar by clicking on the icon highlighted in the screen snippet below:
In the list of PuTTY's Saved Sessions, select wca4z-ra and click Open.
After clicking Open, you will receive a security warning. Select Accept.

This warning should only appear the first time you load the wca4z-ra session.

Scripts will automatically run in the PuTTY session to configure and start the Refactoring Assistant server. In addition, a GitLab server will be started that will be used later in the Transform phase.
Once you receive the message IBM watsonx Code Assistant for Z Refactoring Assistant started in the PuTTY console, you can close PuTTY by clicking on the X icon in the upper-right corner of the PuTTY window and clicking OK on the PuTTY Exit Confirmation popup window.

Refactor your COBOL Programs using Refactoring Assistant¶

The Refactor phase and the remaining phases in the lab (Transform and Validate) use VS Code.

Before you start VS Code, let's get an API key that you will need to enter within VS Code that will grant you access to the watsonx Code Assistant for Z service that runs in IBM Cloud. In your lab environment that API Key is stored in a file on the Windows Desktop. Open the text file named wca4z-key.txt on the Windows Desktop by double-clicking its icon.
Select the entire API key in the text file and use Ctrl-C to copy it to the clipboard.
Open Visual Studio Code (VS Code) by double-clicking its desktop shortcut. (You may need to move or close the window containing your API key in order to see the desktop shortcut.)
At the bottom Explorer pane on the left, expand the IBM WATSONX CODE ASSISTANT FOR Z section if it is not already expanded.

You should see a prompt to Enter API key.
Click the Enter API key prompt. An input bar will appear in the top-middle of the page. Use Ctrl-V to paste the API key that you just copied from the text file and press Enter.

If this was successful, the Enter API key prompt should disappear and you should see a message popup in the lower right that says Connected to watsonx Code Assistant for Z.
Click the user icon in the bottom-left corner of VS Code, and select the option to Sign in with IBM ADDI to use IBM watsonx Code Assistant for Z Refactoring Assistant (1).

A new tab will open in VS Code with a login prompt.
Log in with the following credentials:
- Email address: dev@wca4z-ra.ibm.com
- Password: password
After logging in, a new input field will appear in the top-middle of VS Code to select a project.
Select the GenApp option in this new field.

Another new page will open with an option to search for artifacts within the GenApp project.
Click the search bar, click the dropdown that currently says All artifact types, and select Programs.
From the list of Programs, select GETAAVG and press enter.

A graph showing the dependencies for the GETAAVG program will appear.
Click the GETAAVG program to get a new panel with the program's details, and incoming and outgoing references.
Click on the 3 dots associated with the GETAAVG program and select the Identify conditional statements option.

This will open the COBOL code for the GETAAVG program in VS Code and it will list all of the conditional statements in the code in the bottom left Key Conditions section.
Select the WHEN '0AVMOT' statement under KEY CONDITIONS to jump to the conditional statement in the GETAAVG program code. This is the condition that, when true, calls the functionality that we wish to refactor.
In the KEY CONDITIONS section, right-click the WHEN '0AVMOT' statement and select the option Slice on condition to new service.
A new input field will appear in the top middle of VS Code with a prompt to Enter service name.
Provide a service name of refactor and press enter.

Important: This environment is configured such that you must provide the name refactor in this step, exactly as shown. The reason for this is that a Jenkins pipeline that is triggered when you do a Git commit later expects to find artifacts in a folder of the name refactor, and what you enter in this step will be the name of the folder in which these artifacts are stored. This restriction is just a quirk based on how this particular lab environment was built, and is not a restriction of the watsonx Code Assistant for Z product.
The code will be sliced into new service named refactor and will open in a new tab on right side of VS Code.

This tab shows the code from the WHEN clause that you initially chose, the COBOL paragraph called from that WHEN clause (3100-GET-AVG-MOT-PREMIUM), and then it shows COBOL code from paragraphs called from 3100-GET-AVG-MOT-PREMIUM, and so on. These various code snippets are presented to you in VS Code from information within the refactor.cbls file. refactor.cbls is actually a JSON file, so while you're being shown COBOL source code, this file isn't in a format that can be compiled by the COBOL compiler. The next step will take care of that. You can close this refactor.cbls tab in order to reduce clutter in the VS Code window.
In the left side menu of VS Code under the refactor folder, find refactor.cbls. Right-click refactor.cbls, hover over the option for Z Refactoring Assistant and select Generate Service Code.
A new input field will appear in the top middle of VS Code prompting you to Enter a service program name.
In this field, type GETMAVG and press Enter.

A new tab will open with the refactored code, GETMAVG.cbl.

If it does not automatically open, double click GETMAVG.cbl from the left-side menu to open it.

What you have just done is you have created a COBOL source file, GETMAVG.cbl, with the refactored code, based on the contents of the refactor.cbls file. refactor.cbls is actually a file in the JSON format which, while containing COBOL source code within it, also contains other control information in the JSON format. When you sliced the code into a service, this control file refactor.cbls was created for you, and when you choose Generate service code against this control file, that is when the file containing COBOL source code, GETMAVG.cbl, was created.

Notice that we instructed you to use the name GETMAVG for the generated code. This is because we are refactoring out the motor vehicle policy-related code from a larger program that dealt with multiple policy types. The M in GETMAVG stands for motor vehicle. Think of the first A in GETAAVG as standing for all.

Modify the refactored service code¶

It is important to keep in mind that Refactoring Assistant is an assistant and that it may still be necessary to make some modifications to the refactored COBOL code. These modifications might be necessary for several reasons, including

To adhere to company coding standards
To fix problems that prevent the refactored COBOL code from compiling correctly
To remediate quirks in the refactored COBOL code that may be considered program defects and are likely to be fixed in future updates

In this section we'll make several changes to the refactored code and give a rationale for why these changes are being made.

In VS Code, make the following changes to the GETMAVG.cbl file:
- Comment out the following line as shown below by adding an asterisk in column 7 (it's a COBOL thing)
  
  COPY SQLCA.
Q. Why did you make me do this?

A. This appears to be a quirk in Refactoring Assistant. The original source program did not have a COPY SQLCA. statement in it, but Refactoring Assistant added it. This seems unnecessary because the lines right below that include SQLCA as part of the EXEC SQL statement perform the same purpose.
- Add the following 3 lines after END-EXEC. of INCLUDE SQLCA
```
EXEC SQL
  INCLUDE DGENAPP
END-EXEC.
```
Q. Why did you make me do this?

A. This appears to be a quirk in Refactoring Assistant. The original source program contained these lines, but Refactoring Assistant did not bring it along in its generated COBOL code. This include is necessary because it contains information about the SQL tables used that is necessary to be in the metadata information needed for Java transformation. If you leave this line out then the data model classes will not be generated properly.
- Add a new line after statement PROCEDURE DIVISION and add 1000-MAIN-PARA. on the newly inserted line.
Q. Why did you make me do this?

A. This change may be considered a change to adhere to a corporate standard- perhaps the company's coding standard is that all paragraphs should be explicitly named, so the first paragraph in the PROCEDURE DIVISION is given an explict name.
- After PERFORM 3100-GET-AVG-MOT-PREMIUM add the following lines, making sure to place them in the same column as in the image below.
  
  PERFORM 9000-END-PARA.
  
  1000-EXIT.
Q. Why did you make me do this?

A. The addition of PERFORM 9000-END-PARA. in this case is an example of a personal choice by the COBOL developer. 9000-END-PARA is a simple paragraph that displays a status code. This paragraph is called from other paragraphs in the new COBOL service, but maybe the COBOL developer chose to call the paragraph from this particular spot in the code. The addition of 1000-EXIT. may reflect a company coding convention- there are esoteric reasons why such an empty paragraph may be required by corporate coding standards.
- After 3100-GET-AVG-MOT-PREMIUM add the following line.
  
  MOVE 'Y' TO WS-CUSTOMER-EXISTS.
Q. Why did you make me do this?

A. The developer may have preferred to initialize this variable prior to calling the subroutine.
- Comment out the GOBACK. statement at the end of the code.
Q. Why did you make me do this?

A. Refactoring Assistant added an EXIT PROGRAM statement to the end of the generated service code, so the GOBACK statement is no longer necessary and can be removed.

In the Refactor phase,

We used knowledge about our sample application, GenApp, from the Understand phase to select the GETAAVG COBOL program.
We used IBM watsonx Code Assistant for Z Refactoring Assistant to refactor the 0AVMOT conditional statement by slicing the conditional statement into service code.
We made some minor modifications to the COBOL service code that was generated to help make the point that the Refactoring Assistant is just that, an assistant, and that it is expected that the COBOL developer may have the need or desire to make modifications.
This service code will be used in the following Transform phase.

Transform Phase¶

Overview of the Transform Phase¶

In the transform phase, refactored COBOL code is transformed to Java with the aid of generative AI. This transformation is a three-step process.

First, Java classes are created to implement a data model based on COBOL group items and SQL tables identified in the source code, and Java classes are created to implement the business logic. The methods within the business logic implementation classes are provided as stubs- that is, they are empty. This step is performed by traditional programming logic- in other words, the generative AI model is not used in this step.

In the second step, the business logic is created in Java by the gnerative AI model, and these results from the model are used to fill in the business logic methods that were created empty in the previous step. This is done by sending the source COBOL paragraph to the watsonx Code Assistant for Z service running in IBM Cloud, where this paragraph is combined with program metadata information stored in an IBM Db2 service on IBM Cloud, to form the prompt to the generative AI model. The AI model returns Java code based on this prompt.

In the third step, the Java developer, with help from the COBOL developer if necessary, makes any necessary changes to the returned Java code to ensure that it is compilable and that it performs the function it is expected to perform.

Open Gitlab and Jenkins tabs in Firefox¶

Before we start the transformation process in VS Code, you are going to open two tabs in Firefox- one for Gitlab (a Git-based code repository) and one for Jenkins. Jenkins is an open source automation tool to aid with DevOps and Continuous Integration and Continuous Delivery (CI/CD). Watsonx Code Assistant for Z is designed to integrate with your DevOps processes, and is ideally suited to a Git-based workflow. This lab environment exemplifies this by using Gitlab as its Git-based code repository and Jenkins as its DevOps automation tool.

Save the changes in GETMAVG.cbl by choosing File->Save from the VS Code menu.
Open the Firefox browser in your zVA instance.
Click the GitLab bookmark from the bookmarks toolbar.
The GitLab page will prompt you for login credentials. Click the Username or primary email field, select the wca4z-git saved credentials, and click Sign in.

After successfully logging in to GitLab, the GitLab Projects page will open.
Open the Project named wca4z/COBOLJavaBatch.
Feel free to peruse the files currently included in the project. The most noteworthy thing is that there are no COBOL program source files- files ending in .cbl- at the moment. This situation will change- you will commit the refactored COBOL code to this project soon.
Open another new tab in the web browser and click the Jenkins bookmark from the bookmarks bar.
The Jenkins login page will appear. Select the saved credentials for wca4z-jenkins and click Sign in.
After successfully logging in, the Jenkins Dashboard will appear. The project you'll be working with is named ADDIBuildWCA4ZProject.
Click ADDIBuildWCA4ZProject and see that no previous builds have been run, as indicated in the lower left where it should say No builds in the Build History box, as shown in this screen snippet:

Transform the Refactored Service Code from COBOL to Java¶

Now we'll get back to VS Code to begin the COBOL to Java transformation process.

Navigate back to VS Code. In the far left side of the screen, click the Source Control icon.
Click the + sign in the Changes section of the VS Code Source Control page to stage the refactored COBOL program (GETMAVG.cbl) and the JSON file containing the information about the service (refactor.cbls).

You may need to hover over the Changes line in order for the + sign to appear.

If done correctly, the changes will move to the Staged Changes section.
Add a commit message for the changes. E.g., Adjustments after Refactoring in GETAAVG. Pro tip: You can put whatever you want for a comment, but you have to put in at least one character.
Click the Commit & Push button.
A new pop-up will appear prompting you for GitLab credentials. Enter the following and click Continue to log in.
- Username: wca4z-git
- Password: P@assw0rd
After doing so, your changes should be committed and pushed to the GitLab repository.
Navigate back to the Jenkins page in your web browser.
You should see a new job that was automatically triggered with your pushed changes. Wait until all stages of the job are completed successfully. Greenish colors are good and reddish colors are not so good.
Click the Build number from the list on the left, and then click Console Output.

This could be #2 or #3, for example.

The log for the job will appear.
Look through the job log to see the actions that were performed.

This Jenkins build was triggered by the commit you made to GitLab. The purpose of the build is to create metadata information that is used by the watsonx Code Assistant for Z service on IBM Cloud. This metadata information will be combined with a COBOL paragraph's source code to form a prompt to the large language model (LLM). The LLM returns Java code based on the prompt.

Scroll through the Console Output, and look for:

DELETE FROM EZSCH.WCAZCATALOG

EZSCH.WCAZCATALOG is the Db2 table that will contain the metadata information about the refactored COBOL code. This table is created the first time that the process that creates the metadata information is run. The message SQL0204N "EZSCH.WCAZCATALOG" is an undefined name indicates that this table does not exist. That message is okay and is expected since this is the first time this Jenkins build has run- the Jenkins build includes a step to delete all the rows because at the end of the build new rows will be inserted based on the refactored COBOL code that you have committed. If you were to do another commit (which you won't have to do if the lab works perfectly but you might have to do for debugging reasons) then you would see different messages after the DELETE FROM because now your table does exist.

Look for messages like this:
```
Found an updated file: "GETMAVG.cbl"
Resolved path to file: "C:\data\GIT_REPOS\refactor\cobol\GETMAVG.cbl"
Adding program "GETMAVG" to import queue

Populating additional metadata for WCA4Z from ADDI and DDL

Populating metadata for program GETMAVG
Generating PrimaryKeys.csv and ForeignKeys.csv
Importing data into the database
Done.
```
The program that you committed, GETMAVG.cbl, was detected, and metadata about the program, including information about the primary keys and foreign keys of the Db2 tables used by the program, is written to the database that watsonx Code Assistant for Z uses to help construct the prompt to the LLM.

Note: The Jenkins pipeline that is running here is not provided with watsonx Code Assistant for Z. The pipeline takes advantages of components provided by watsonx Code Assistant for Z, but the pipeline itself is tailored to this lab environment. There are other ways to create and store this metadata information, and in fact the way that it is created and stored has changed from version 1.x to version 2.x of watsonx Code Assistant for Z. This lab doesn't go into detail on this topic.
Navigate back to the GitLab tab in the browser and refresh it.

You should see a few changes.
- a new commit with a green check mark, and
- a new refactor folder that was not present before
Open the refactor folder in the GitLab browser page, then open the cobol sub-folder.

The GETMAVG code will now be present.

Let's review Here's what transpired in the last several steps (from step 14 up to this point):
- When you did the Commit and Push in step 4, it pushed the changes you made with Refactoring Assistant up to the source code repository on your Gitlab server
- This triggered the Jenkins pipeline which executed a series of steps. The purpose of these steps was to inspect the code changes, incorporate them into an ADDI project associated with your source code repository, create metadata information that will be used for transforming the COBOL code to Java, and writing this metadata information to the IBM Cloud Db2 service that the watsonx Code Assistant for Z service uses.
Navigate back to VS Code.
Click the Explorer icon in the upper left, then, within the refactor/cobol folder, right-click the GETMAVG.cbl, hover over watsonx Code Assistant for Z, and choose Select COBOL for transformation.

Note: the same task can be performed by selecting the Import COBOL button in the bottom-left corner of VS Code under the IBM WATSONX CODE ASSISTANT FOR Z section.

Either way, the GETMAVG.cbl file should now be present in the IBM WATSONX CODE ASSISTANT FOR Z section in the bottom left of VS Code.
In the IBM WATSONX CODE ASSISTANT FOR Z section in the bottom left, click the icon next to GETMAVG.cbl to Generate Java classes.

A new input bar will appear in the top middle of VS Code, prompting you for a Java directory,
Select Input absolute path, click in the blank space on the right side of the input field to remove the highlight from the default path, and then add the following to the end of the default path: \getmavg\src\main\java.

The absolute path should be the following:

c:\Users\Administrator\Desktop\WCA4Z Lab Data\COBOLJavaBatch\getmavg\src\main\java
Press Enter

A new tab for Java Class design should open.

The metadata information that was just created from the Jenkins pipeline was used to construct the information that is presented to you in this tab.

Here is a recap of the classes that are being created:
1. A Java class in the datamodel package was created for each of the three Db2 tables referenced in the code: Customer, Motor, and Policy. The variables in each class correspond to the columns in the Db2 table.
2. A Java class was created in the implementation package corresponding to the name of our refactored COBOL program- Getmavg.
3. For each 01-level group item in the refactored COBOL program, a class is created in the implementation package- in our case, WsWork and WsInRec, which correspond to the COBOL group items WS-WORK and WS-IN-REC, respectively.
Expand the different artifacts using the down arrows. Keep all of the default values.

Notice that there are methods listed under the Getmavg package and the WsWork package. These are java methods that will correspond to COBOL paragraphs from the refactored COBOL program. Watsonx Code Assistant for Z placed some of the methods in the Getmavg class and some in the WsWork class. Those classes that manipulate a group item are candidates to be placed in the class for that particular group item (e.g., WsWork) instead of in the class named for the refactored COBOL program (e.g., Getmavg).
At the bottom right of Java Class design tab, click Generate Java classes.
In the left side menu of VS Code, navigate to the getmavg\src\main\java\com\ibm\wcaz folder to see the list of generated Java classes.
Copy the JdbcConnection.java file into the implementation folder, \getmavg\src\main\java\com\ibm\wcaz\implementation. The easiest way to do this on the zVA is probably to right-click and copy against JdbcConnection.java and then on the implementation folder name do right-click and paste. Trying to drag and drop defaults to move instead of copy which is why we advise to use right-click context menus instead of drag and drop. We're asking you to copy for debugging purposes only- in case we instruct you to remove the implementation folder during problem determination steps, it is good to have the original copy.

JDBC stands for Java DataBase Connectivity. The details for configuring a connection from Java programs to data bases may be standardized for a company, and this program exemplifies using a particular class for the connectivity. So the Java developer will use this class and you will see in a later step how they must make minor changes to the code returned by the Large Language Model (LLM) in order to work with this class.
When you copied the file in the previous step, VS Code extensions for Java activated since this was the first time in the lab instructions you worked directly with a java file. Note: It is possible that you looked at some java files on your own out of curiousity a little while ago and the actions taken by VS Code as described in this step may already have occurred.

A new section named JAVA PROJECTS will appear at the bottom-left of VS Code and the Java projects will be generated.

You may need to expand the JAVA PROJECTS section to see the projects. You aren't really going to take specific actions within the JAVA PROJECTS section, so you can collapse this section when you're done perusing it. What is important here is to wait for the message Java: Ready to appear in the lower left of VS Code. It may take a couple of minutes for things to settle down to the point where you see Java: Ready. Important: Wait for the message Java: Ready to appear.
The Java classes and method names can be found in the refactor\cobol folder in the IBM WATSONX CODE ASSISTANT FOR Z section.

You may need to expand the IBM WATSONX CODE ASSISTANT FOR Z section to see the classes and methods.
In the refactor\cobol folder, click on the method named getAvgMotPremium3100.

The source code for WsWork.java is displayed and the getAvgMotPremium3100 method is highlighted. Notice that the body of this method is empty- there is nothing betwen the curly brackets {}. This empty method was set up during the Generate Java classes action you took moments ago with the expectation that the contents of the method will be generated by the LLM. This is what happens during the Generate Java method action that you will be performing on each empty method.
In the refactor\cobol folder, click the icon next to the getAvgMotPremium3100 filename to generate the Java method.

The large language model (LLM) will begin to generate Java code for the getAvgMotPremium3100 Java method which matches the functionality of the 3100-GET-AVG-MOT-PREMIUM COBOL paragraph.
After the Java method gets generated in the right-side panel, click the Insert button.

The generated Java code getAvgMotPremium3100 will be inserted into the body of the method.

In the left side menu, you can see that getAvgMotPremium3100 now has a check mark next to its icon. (Look closely, this is a small check mark on a tiny icon, so it is a bit of an "eye test".) This indicates that the method has been generated. Now that you've inserted the Java code into the method, you can close the Java method generation tab to reduce clutter in the VS Code window.
Repeat this process (steps 23-25) for the remaining methods, one method at a time, until they are all checked off.

Fix problems identified in the generated Java code¶

It is anticipated that the code returned from the LLM will not be perfect and ready to be run without change. There will very likely be problems in the Java code that will be identified in VS Code. The problems will typically fall into one of these categories:

problems that are trivial to fix, and often can be fixed by a Quick fix offered by VS Code, such as missing imports
problems that require a little bit of investigation by the Java developer but are within the knowledge domain of the Java developer
problems that may require some knowledge of the original application and thus may require some collaboration with the COBOL application developer

Note: The LLM used by watsonx Code Assistant for Z is constantly improved and is updated frequently. It is expected that the number of problems to resolve will decrease over time as the LLM improves- in fact, there is always the chance that recent model updates might cause the results that are returned during the lab to differ from what is documented here, in which case the instructions as shown here may not work correctly! If this occurs, the instructors will tell the students during the lab what alterations to the lab instructions are necessary in order to resolve the problems. (Or they'll tell you to go home early if they can't figure it out.) The remainder of this section lists the problems that we expect you to have to contend with, subject to the previous disclaimer.

Select View->Problems from the VS Code menu to see a list of problems in the bottom portion of VS Code.

You do not need to worry about every problem identified, just the ones in WsWork.java and Getmavg.java which are the two Java classes that contain methods that were generated by the LLM.
Let's start with the errors in WsWork.java.

We expect that you will receive a few errors of the type NAME cannot be resolved to a type where NAME will be PreparedStatement, SQLException, and ResultSet. These are easy to fix all at once- click on any one of these errors in the Problem view, and you will be taken to its occurrence in the code window. Hover over the red-underlined text associated with the error, click Quick fix, and select Add all missing imports. By choosing Add all missing imports, it will attempt to implement the fix for all of these missing types, one at a time. See the screen-snippet below for hints on how to do this:

Note: Be alert for a prompt at the top of your VS Code window which may appear if multiple Java libraries configured on your system offer this class. If prompted, select the option that starts with java.sql for each import.
Still within the WsWork.java file, you may see two problems for connection cannot be resolved or is not a field. This is needed because the JDBCConnection.java class we are using does not provide a connection object, but rather a connection method. This is an example of how a company-specific detail (e.g., using a company-mandated JDBC Connection class) might require a modification to the generated code. To resolve this, for each problem, click on it to be taken to the code, then, manually change connection to connection(). The screen snippet below shows where to make this change in the getAvgMotPremium3100() method, but you will have to make this change in the validateCustomer310a() method as well.
You may notice a new problem has appeared under WsWork.java- Unhandled exception type ClassNotFoundException. This occurred when you changed connection to connection(). You made that change in two places but you only received this problem once. The problem is applicable to both places, but the tooling won't recognize it in the getAvgMotPremium3100() method until you resolve the sqlCode cannot be resolved to a variable problem, which we'll cover in the next step. After that is resolved, we'll tell you how to fix the ClassNotFoundException-related problem.
If you have errors in getAvgMotPremium3100() stating that sqlcode cannot be resolved to a variable, similar to what is shown in the screen snippet below, read the instructions below the screen snippet for advice on how to remediate this. Follow the instructions carefully, you will do more typing or cutting and pasting in this step than any other step in the lab.

This sqlcode Java variable originated from the COBOL variable SQLCODE which is defined in the SQLCA group data item. This variable holds the result of a SQL call. In Java, a non-zero SQL code can be retrieved from the getErrorCode() method of the SQLException class. Thus, one way to resolve this unreferenced variable is to move the handling of it into the catch clause that handles a SQLException. Right now, the sqlCode variable is being checked after the try/catch statement. We think we can improve upon the model's output here. Remember, watsonx Code Assistant for Z is an assistant- you are the boss, and you can overrule your assistant.

The following set of instructions will provide guidance to help you to move the sqlcode variable to the catch clause, where it belongs, improving the code and resolving the problem. To perform these steps you may have to do some typing, some cutting and pasting, and some deletions. This is probably the most difficult step in the lab- take care when performing this step, but, to be safe, we've included the complete source code for the getAvgMotPremium3100() at the end of this step for your reference.

All three of the sqlCode cannot be resolved to a variable problems are very close to each other in the code. Click on any one of them from the Problems view to be taken to the area of the code that you will be modifying. Just above where these errors occur, you'll notice a catch clause. Change this catch clause of the SQLException from
```
} catch (SQLException exception) {
        this.setWsStatusCode("02");
        endPara9000();
        return;
    }
```
to
```
} catch (SQLException exception) {
  int sqlCode = exception.getErrorCode();
  System.out.println("SQLCODE:" + sqlCode);
  if (sqlCode == 100) {
    this.setWsStatusCode("02");
  } else {
    this.setWsStatusCode("16");
  }
  endPara9000();
  return;
}
```
This handles non-zero SQL codes by setting wsStatusCode to 2 for SQL Code 100 and to 16 for any other non-zero SQL Code. (This may seem odd but it is what the original COBOL was doing.)

Since a SQL code of zero does not cause a SQLException, we can set wsStatusCode to 00 prior to making the SQL call. Add this.setWsStatusCode("00") at the top of the try clause (just a few lines above where you just matde the changes to the catch clause) in getAvgMotPremium3100(), prior to making the SQL call. See the code snippet below for where it belongs:
```
...
  if (this.getWsCustomerExists() == 'Y') {
try {
  this.setWsStatusCode("00");    // Insert this line at top of the 'try'
  ResultSet rs = JdbcConnection.connection().createStatement().executeQuery(
...
```
Now you can get rid of the code shown below, just after the try/catch clause, because you set wsStatusCode to 00 prior to the SQL call, and you are relying on the catch clause to change wsStatusCode appropriately if a SQLException occurs:
```
        System.out.println("SQLCODE:" + sqlCode);
    if (sqlCode == 0) {
        this.setWsStatusCode("00");
    } else if (sqlCode == 100) {
        this.setWsStatusCode("02");
        endPara9000();
        return;
    } else {
        this.setWsStatusCode("16");
        endPara9000();
        return;
    }
```
At this point you should see a second Unhandled exception type ClassNotFoundException problem appear in your Problems view. This problem appears because the connection() method throws a ClassNotFoundException, which is not handled by the try/catch block returned by the LLM. For each of these two problems, click on them in the Problems view to get to where they occur in the code window, hover over the red underline, click Quick Fix, then click Add catch clause to surrounding try. The red underline indicating an error should disappear. The screen snippet below gives hints from within the getAvgMotPremium3100() method, and you'll need to do this within the validateCustomer310A() method as well:

The instructions had you making several changes in getAvgMotPremium3100(). In case your edits didn't go smoothly, here is what this method should now look like. If necessary, you could delete that method in your code window and replace it with the contents of the method shown here. You won't have to do this if your editing went smoothly.

public void getAvgMotPremium3100() {
  this.setWsCustomerExists('Y');
  validateCustomer310A();
  if (this.getWsCustomerExists() == 'Y') {
    try {
      this.setWsStatusCode("00");
      ResultSet rs = JdbcConnection.connection().createStatement().executeQuery(
      "SELECT AVG(MOT.PREMIUM) FROM CUSTOMER CUST INNER JOIN POLICY POL ON POL.CUSTOMERNUMBER = CUST.CUSTOMERNUMBER INNER JOIN MOTOR MOT   ON POL.POLICYNUMBER = MOT.POLICYNUMBER WHERE POL.CUSTOMERNUMBER = "
          + this.getWsCustomerNumber());
      rs.next();
      this.setWsAvgPremium(rs.getInt(1));
    } catch (SQLException exception) {
        int sqlCode = exception.getErrorCode();
        System.out.println("SQLCODE:" + sqlCode);
        if (sqlCode == 100) {
          this.setWsStatusCode("02");
        } else {
           this.setWsStatusCode("16");
        }
        endPara9000();
        return;
    } catch (ClassNotFoundException e) {
        // TODO Auto-generated catch block
        System.out.println(e.printStackTrace());
    }
  } else {
    this.setWsStatusCode("08");
    System.out.println("INVALID CUSTOMER!!!");
    endPara9000();
    return;
  }
checkIfOverpaid4000();
}

Any problems remaining in Getmavg.java or WsWork.java should be trivial- you may see one for an import that is never used. You may delete the unused import using a quick fix. Our empty COBOL paragraph 1000-EXIT was turned into an empty method except for a TODO comment, so you can remove the TODO comment from the code as well to remove this from the problem list. Similarly, the catch clauses you added to fix the problems from the JdbcConnection.connection() method may each have a TODO comment, so you can remove these as well.

You should no longer have problems in the WsWork.java or Getmavg.java files indicated by red numbers next to the filenames. You may have some warnings or TODOs, but these can be ignored. All problems with the transformed Java code should be fixed, and it should be compilable now, which is a preqrequisite for the next phase, which is the Validate phase.

In this Transform phase,

We used the refactored service code GETMAVG from the Refactor phase.
We generated Java classes and Java methods for the GETMAVG service.
We made necessary fixes to the LLM-generated Java code.

In the next phase, you will use IBM watsonx Code Assistant for Z Validation Assistant to validate that the original COBOL and transformed Java produce the same results.

Validate Phase¶

Overview of Validate Phase¶

The purpose of the Validate phase is to ensure the semantic equivalence of the refactored COBOL code with the generated (and possibly modified) Java code.

The general flow is this:

The COBOL developer compiles the refactored COBOL with the TEST(DWARF) compiler option which produces debugging information in the load module created by the compilation and link-editing.
The COBOL developer uses the watsonx Code Assistant for Z Validation Assistant VS Code extension to read the compiler listing, compile and run test cases using the IBM z/OS Debugger, and saves the output from these test cases.
The Java developer uses the watsonx Code Assistant for Z Validation Assistant to run tests against the generated Java method which will compile and run Junit tests locally on the developer workstation and compare the output to the output of the corresponding COBOL test case.

In the lab you will perform all of these steps in one sitting. In the real world scenario, the COBOL developer would likely run the COBOL portion of the process on their laptop or workstation and then provide the folder which has these results to the Java developer who would put this folder on their laptop or workstation prior to running the Java tests.

Generate COBOL outputs¶

Establish credentials in ZOWE Explorer¶

In VS Code, click the Zowe icon on the left side.
In the JOBS section near the lower left, right-click on the zos.dev profile and choose Manage profile:
A menu will appear in the top middle of VS Code. Click on Add credentials:
You will be prompted first for a username, and then for a password. Enter the following credentials.
- Username: ibmuser
- Password: sys1
In the DATA SETS section, expand both the Favorites and zos.dev folders.
Click the search button next to the bottom zos.dev folder.

You may need to hover over the zos.dev bar for the search icon to appear.
Note: You may be prompted first for a username, and then for a password. If not, proceed to the next step. If you are, enter the following credentials.
- Username: ibmuser
- Password: sys1
You will be prompted to enter a dataset filter. Enter ibmuser.wca4z.** (it may be presented to you as a choice in the dropdown list) in the bar at the top of the page and press Enter.

Multiple data sets will appear in the zos.dev folder, including IBMUSER.WCA4Z.COBOL.

Generate COBOL compiler listing¶

Back in the DATA SETS section of the ZOWE explorer pane, expand Favorites and then zos.dev underneath it, and then right-click on IBMUSER.WCA4Z.COBOL and select Upload member.
Browse to C:\Users\Administrator\Desktop\WCAZ Lab Data\COBOLJavaBatch\refactor\cobol, select GETMAVG.cbl, and click Upload file.

You should now see the GETMAVG file under IBMUSER.WCA4Z.COBOL.
Expand the IBMUSER.WCA4Z.CNTL folder, right-click GETMAVG, and select Submit Job.
You will be prompted to confirm that you want to submit the job. Click the Submit button.
After you submit the job, you will get a pop-up in the bottom-right corner with the Job ID. Click on the Job ID to go to it.

Note: if the job notification disappears before you click on it, you can find it again by clicking the Notifications button in the bottom-left corner of VSCode.
You should see a CC 0004 next to the job name and number. Any condition code higher than 4 should be investigated- ask for help from an instructor if necessary. As long as your condition code is 4 or 0, right-click on the Job name and select Download all.
Navigate to C:\Users\Administrator\Desktop\WCAZ Lab Data\COBOLJavaBatch\logs and click Select to save the files.
Navigate back to the file Explorer in VSCode and find the logs folder.
In the COBOL/GETMAVG folder, right-click sysprint.txt and select Rename... and then rename the file to getmavg.log.

Generate COBOL values¶

Right-click getmavg.log, hover over watsonx Code Assistant for Z Validation Assistant, and then select Generate COBOL Values for Testing.
You will be prompted to select a Load library at the top middle of VS Code. Enter or select IBMUSER.WCA4Z.LOAD and press enter.

This step was successful if you see the message Completed generating cobol values for testing at the bottom of your Terminal window.

Run Java equivalence tests¶

Expand the IBM WATSONX CODE ASSISTANT FOR Z section, expand WsWork.java, and click on calcReturnPremium4100.

The code will display in the main window and the calcReturnPremium4100 method will be highlighted.
Double-click the method name in the main window so that just the method name is highlighted. Then right-click the highlighted method name, hover over watsonx Code Assistant for Z Validation Assistant and select Run Equivalence Test.

Wait until you see the message Equivalency Tests Complete.

Note: You may see an error message popup in the lower right that says Failed to perform operation: SyntaxError: Expected double-quoted property name in JSON at position 188 (line 4 column 5). You may ignore this message- it is due to a syntax error in a settings file provided in the lab environment.

In the IBM WATSONX CODE ASSISTANT FOR Z VALIDATION ASSISTANT pane, a green checkmark icon next to the test means the test passed and a red 'x' icon next to the test means that it failed. This pane is on the left, probably underneath the TIMELINE pane, and you will probably have to expand the pane in order to see these test results. Ask an instructor for help if your test didn't pass.
Repeat steps 1 and 2 for Java methods checkIfOverpaid4000 and MainPara1000.

In the Validate Phase,

We generated COBOL values for the GETMAVG refactored service.
We ran JUnit tests to compare the values from the transformed Java code.

Lab summary¶

Congratulations for completing the lab! In this lab, you performed tasks for several personas:

You performed the Understand phase in the role of an application architect
You performed the Refactor phase in the role of a COBOL application developer
You performed the Transform phase in the role of a Java application developer
You performed the Validate phase in the role of a Java application developer

Ended: Lab 2 - Understand, Refactor, Transform, Validate