JCL Code Explanation

Edit online

Code Explanation is available in two types: chat experience and code selection. By using the chat experience feature, seamlessly engage in a conversation with AI, getting quick and accurate answers to questions about code.

2.7.0+ You can generate simple or detailed explanation for an entire JCL job.

2.1.0+

You can generate an explanation for the selected JCL step. A split editor panel opens on the right of the VS Code window to display the simple or detailed explanation.2.3.0+For JCL, back-end service is enhanced to provide improved explanations for a broader range of z/OS® programs.

Note: Code explanation is only supported for JCL steps that contain EXEC PGM=<IDENTIFIER> and JCL jobs that contain //<IDENTIFIER>JOB.

Getting started with JCL Explanation on VS Code

Complete the following steps to get started with JCL explanation:
  1. On the VS Code window, in the explorer panel, left-click the JCL file to open it in the editor panel.
  2. Select and right-click the portion of JCL code that you want to generate an explanation for.

    Alternatively, you can double-click the step headers in the outline panel to make automatic step selections in the editor panel.

  3. Hover over watsonx Code Assistant™ for Z to open the menu.
  4. Select any one of the explanation types: Simple or Detailed.

For code explanation examples, see JCL examples topic.

Generate and insert comments

2.6.10+ You can generate and add code comments for a selected code block by using the Document Code Lens or for a complete file by using the /document command.

If the AI Chat option in VS Code extension settings is disabled, the output is displayed in the side panel. If the AI Chat option is enabled, the output is displayed in a chat window.

To generate and insert code comments in the side panel by using the Document Code Lens, complete these steps.
  1. On the VS Code window, in the explorer panel, left-click a file to open it in the editor panel.
  2. Click Document Code Lens above a relevant code block. If the AI Chat option in VS Code extension settings is disabled, the Code Explanation side panel opens to the right and displays the output for the selected code block.
  3. In the panel view, click the icon labeled Insert as comment to insert the generated comments above the corresponding code block in the source file.
Note: For any known issues or limitations, refer to the Troubleshooting topic.

Using the Chat Experience feature

Note: 2.7.10+ You can generate enhanced explanations by including the comments in the source code. To do so, enable the Z Code Assistant: Enable Include Comment option in the settings.

2.8.0+To generate explanation through watsonx Code Assistant for Z Chat, see Using watsonx Code Assistant for Z Agentic chat IDE.

(2.7.20+ or earlier) To generate explanation through Chat, do the following:

  1. Click the watsonx Code Assistant extension on the side panel to open the Chat Experience feature.
  2. Enter /explain and then enter @. A menu with a list of files opens in the VS Code workspace.
  3. Select the program and press Enter. Code explanation for the selected file is displayed in the chat window. You can type in follow-on questions in the chat area to seek further responses.

Alternatively with the code open in the VS Code workspace, select an entire JCL job or a JCL step, right-click the code snippet, and select Generate Detailed Explanation to view code explanation in the chat window. Follow-on questions are not supported for this method.

Working with code comments by using Document Code Lens

2.6.10+ To generate and insert comments for a code block by using the Chat Experience feature, complete the steps mentioned for Document Code Lens procedure. However, make sure that the AI Chat option is enabled in VS Code extension settings.

The watsonx Code Assistant chat window opens to the left and displays output for the selected code block.
  1. In the chat response, click the title of a code block to navigate to its location in the source file.
  2. Next to each code block title in the chat response, click the Insert icon to insert the comments above that block in the source file.

Working with code comments by using /document command

To generate code comments for the selected code file by using the /document command, complete these steps.
  1. Click the watsonx Code Assistant extension on the side panel to open the Chat Experience feature.

    Make sure that the AI Chat option is enabled within the watsonx Code Assistant for Z extension

  2. Enter /document and then enter @. A menu with a list of files opens in the VS Code workspace.
  3. Choose the required file.

    After a few seconds, watsonx Code Assistant generates separate comments for all code blocks (outline items that have a code lens) within the selected file in the chat window. In the chat response, you can click the title of a code block to navigate to its location in the source file.

  4. Next to each code block title in the chat response, click the Insert icon to insert the comments above that block in the source file.

Getting started with JCL Explanation on Eclipse

2.3.0+
When used with IBM® Developer for z/OS or z/OS Explorer, these features are available.

  • From the outline view for JCL Editor, EXEC steps are enabled for explanations. You can choose to use a context menu or a keyboard shortcut.

  • If you select part of an EXEC step in the JCL Editor, your selection is expanded to select the entire EXEC step.

  • If you fail to select part of an EXEC step you get an error dialog explaining to you that only a single EXEC steps can be selected for explanation.

The procedure for code explanation is mostly the same for both VS Code and Eclipse environments.