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.

1. Log in to your TechZone lab environment. You can find connection details on the Lab Assignments page.

2. On your TechZone lab environment's desktop, find the Git bash icon and double-click it in order to open up a terminal window:

   

3. 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.

4. 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:

   

5. 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:

   

6. 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.

7. 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.

   

8. 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.

   

9. 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.

10. 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!

1. 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.

   

2. 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.

   

3. 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.

4. 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.

   

5. 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.

   

6. 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

1. 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.)

   

2. 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:

   

3. 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.)

   

4. 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:

   

5. 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,

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

This completes the Code Explanation lab.