Modernize your mainframe application

Preview

This product or feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. Pre-GA products and features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

In this guide, you'll learn how to use the Cloud Code for VS Code extension to modernize your legacy mainframe application.

Mainframe Modernization Code Rewrite enables an iterative approach to code rewrite for customers and partners. It's typically used after completing an assessment with the Mainframe Assessment Tool (MAT). This extension integrates Mainframe GenAI capabilities for code analysis, specification, code generation, and test generation, providing an interactive development experience.

Before you begin

Note: We recommend using this feature for workspaces that are limited to a maximum of 5 million lines of code in total.

1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

3. Make sure that billing is enabled for your Google Cloud project.

4. Enable the Vertex AI API.

   Enable the API

5. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

6. Make sure that billing is enabled for your Google Cloud project.

7. Enable the Vertex AI API.

   Enable the API

8. Install the Cloud Code extension if you haven't already.
9. Install the Google Cloud CLI if you haven't already.

Setup Mainframe Modernization Code Rewrite

The following sections describe how to setup Mainframe Modernization Code Rewrite. You'll first need to enable Mainframe Modernization Code Rewrite in your IDE, and then connect it to Vertex AI.

Enable Mainframe Modernization Code Rewrite

To enable Mainframe Modernization Code Rewrite, follow these steps:

1. Open the Command Palette with Ctrl/Cmd+Shift+P.

2. Select the Preferences: Open User Settings (JSON) command.

   To enable Mainframe Modernization Code Rewrite, add the "cloudcode.beta.enableMainframeModernization": true setting to your settings.json file:

   {
       "cloudcode.updateChannel": "Insiders",
       "cloudcode.beta.enableMainframeModernization": true
   }
   

3. Open the Command Palette again (press Ctrl/Cmd+Shift+P) and select the Developer: Reload Window command.

Connect Mainframe Modernization Code Rewrite to Vertex AI

To connect Mainframe Modernization Code Rewrite to Vertex AI, follow these steps:

1. In a terminal window, run the following command:

   gcloud auth application-default login
   

2. Follow the on-screen instructions in the newly opened web browser window.

3. Follow the prompts to sign in to Google Cloud.

4. Select the project you'd like to use.

5. Run the Developer: Reload Window command.

After setting up, you can open any workspace or folder that includes mainframe code, and execute the Generate Specification Summary and Generate Modernized Code commands on COBOL, JCL, Easytrieve, and HLASM.

Generate specification summary

The Cloud Code: Generate Specification Summary for Active File command lets you create a neutral language specification for your legacy mainframe code. COBOL, JCL, Easytrieve, and HLASM are supported.

You can access a specification summary either from the Command Palette or from the Explorer view:

Command Palette

1. In the editor, select the source file you want to use to make it the active file.

2. To open the Command Palette, press Ctrl/Cmd+Shift+P.

3. Search for and select the Cloud Code: Generate Specification Summary for Active File command.

A specification summary appears next to the code.

Explorer

1. In the activity bar, click Explorer or press Ctrl/Cmd+Shift+E.

2. Right-click your preferred source file and select Generate Specification Summary.

A specification summary appears next to the code.

Annotate mainframe legacy code

To guide the specification summary generation process, you can annotate your legacy code by adding comments. To annotate a JCL job or a COBOL program, look for the add Add button next to the job/program definition line:

JCL Job

COBOL Program

1. To open an inline CMS view that lets you annotate your job/program, click add Add. After adding your comment, click Create Note to save it.

2. When the annotation is saved, use the Generate Specification Summary command to generate a specification for your job/program, guided by your comment.

   You can then edit your annotation to refine the provided guidance or delete it if you no longer want the model to take it into consideration.

Generate modernized code

The Cloud Code: Generate Modernized Code for Active File command lets you create modern code out of your mainframe legacy code.

Supported source languages: COBOL, JCL, Easytrieve, and HLASM.

Supported target languages: Java, C#, Python, SQL.

You can access this command either from the Command Palette, or from the Explorer view:

Command Palette

1. In the editor, select the source file you want to use to make it the active file.

2. Open the Command Palette by pressing Ctrl/Cmd+Shift+P.

3. Search for and select the Cloud Code: Generate Modernized Code for Active File command.

4. Select the target language in which you want the modernized code to be generated.

   The generated modernized code appears in the editor as a new untitled file.

Explorer

1. In the activity bar, click Explorer or press Ctrl/Cmd+Shift+E.

2. Right-click the source file that you want to generate modernized code for and select Generate Modernized Code.

3. Select the target language in which you want the modernized code to be generated.

   The generated modernized code appears in the editor as a new untitled file.

Modify settings

Mainframe Modernization Code Rewrite has the following settings you can configure either at the workspace scope, or at the (global) user settings scope.

To modify settings at the workspace level, press Ctrl/Cmd+Shift+P to open the Command Palette and select the Preferences: Open Workspace Settings (JSON) command.

To modify settings at the global user settings level, press Ctrl/Cmd+Shift+P to open the Command Palette and select the Preferences: Open User Settings (JSON) command.

Here's an example of a settings.json file that includes all of the extension's configuration properties:

{
    "cloudcode.beta.enableMainframeModernization": true,
    "cloudcode.beta.mainframeModernization.enableGoogleAnalytics": true,
    "cloudcode.beta.mainframeModernization.enableCloudLogging": false,
    "cloudcode.beta.mainframeModernization.model": "gemini-2.0-pro",
    "cloudcode.beta.mainframeModernization.codeGenerationSettings.targetLanguage": "csharp",
    "cloudcode.beta.mainframeModernization.codeGenerationSettings.techStackHints": [
        "Do not print messages directly to the console; use a logging framework instead."
    ],
}

Enable and disable Google Analytics

This configuration property enables or disables the collection of usage analytics for the extension.

• Configuration property name: cloudcode.beta.mainframeModernization.enableGoogleAnalytics.

• Example configuration value: false.

• Default value: true (Analytics are enabled).

Enable and disable Cloud Logging

This configuration property controls whether Logging is enabled or not.

• Configuration property name: cloudcode.beta.mainframeModernization.enableCloudLogging.

• Example configuration value: true.

• Default value: false (Cloud Logging is disabled).

Model

When this configuration property is set, Mainframe Modernization Code Rewrite uses the Gemini model specified in the configuration.

• Configuration property name: cloudcode.beta.mainframeModernization.model

• Example configuration values: "gemini-1.5-flash", "gemini-1.5-pro", "gemini-2.0-flash", "gemini-2.0-flash-lite", or "gemini-2.0-pro".

• Default value: "(default)" (Ask every time).

Target language

When this configuration property is set, the Generate Modernized Code command no longer asks you to select the target language when generating code, and uses the language set in the property instead.

• Configuration property name: cloudcode.beta.mainframeModernization.codeGenerationSettings.targetLanguage

• Example configuration values: "java", "csharp", "python", or "pgsql".

• Default value: null (Ask every time).

Code generation tech stack hints

When this configuration property is set, the Generate Modernized Code command passes the specified list of tech stack hints as additional instructions to the LLM when generating code. This configuration can be used as a guidance for adjusting target architecture, frameworks and code styling.

• Configuration property name: cloudcode.beta.mainframeModernization.codeGenerationSettings.techStackHints

• Example configuration value:

  [
    "Do not print messages directly to the console; use a logging framework instead.",
    "when generating java code - use Spring Boot version 3 as the framework"
  ]
  

• Default value: [] (An empty list; no tech stack hints).

Delete Mainframe Modernization Code Rewrite Data

To remove all data stored locally by Mainframe Modernization Code Rewrite for the current workspace, follow these steps:

1. Open the terminal by selecting View > Terminal from the menu bar, or by pressing the ⌃ keyboard shortcut.

2. Enter the following commands into the terminal:

Linux (Bash or Zsh)

workspace_id=$(printf %s "$PWD$(stat -c '%i' .)" | md5sum | head -c 32)
workspace_storage_dir="$HOME/.config/Code/User/workspaceStorage/$workspace_id"
rm -r "$workspace_storage_dir/googlecloudtools.cloudcode/mainframe/"

Windows (PowerShell)

$workspacePath = (Get-Location).ToString()

$tempFile = (New-TemporaryFile).FullName
($workspacePath.Substring(0, 1).ToLower() + $workspacePath.Substring(1) +
    (([decimal](Get-Date (Get-ItemProperty . |
        Select-Object -ExpandProperty CreationTimeUtc) -UFormat %s) * 1000) -split '\.')[0]
) | Out-File -FilePath $tempFile -Encoding ascii -NoNewline
$workspaceId = (Get-FileHash -Algorithm MD5 -Path $tempFile).Hash.ToLower()
Remove-Item $tempFile

$workspaceStorageDir = "$env:APPDATA\Code\User\workspaceStorage\$workspaceId"
Remove-Item -Recurse "$workspaceStorageDir\googlecloudtools.cloudcode\mainframe"

Troubleshoot

This section outlines the known issues of Mainframe Modernization Code Rewrite and provides troubleshooting steps:

Vertex AI not available in Google Cloud project

If the Generate Specification Summary or Generate Modernized Code commands execute for a long time and then fail, the Vertex AI API might not be enabled, or has exceeded its quota in the selected project. To confirm that this is the issue, click the Go to output button.

If the Go to output button isn't available, follow the steps in Inspect the output channel. In the output channel, look for an error message containing "Vertex.GenerateContent failed". For example, here is an error message caused by Vertex AI API not being enabled in the selected Google Cloud project:

"generic::unknown: retry budget exhausted (30 attempts): Vertex.GenerateContent failed: 403 Forbidden (403)"

To resolve this issue, either:

• Confirm your Vertex AI API is enabled on the Google Cloud project.

• Switch to another Google Cloud project with enabled Vertex AI API.

Mainframe Modernization Code Rewrite commands are not available

If commands such as Generate Specification Summary or Generate Modernized Code are not available in the Command Palette, this might indicate that the Mainframe Modernization CLI tool failed to install. To confirm that this is the case, check whether the following executable file is missing:

• On Linux: ~/.cache/cloud-code/mainframe/bin/codegen
• On Windows: %LOCALAPPDATA%\cloud-code\mainframe\bin\codegen.exe
• On macOS: $HOME/Library/Application Support/cloud-code/mainframe/bin/codegen_macos

If this is the case, try to resolve the issue by performing the following tasks:

1. Open the Command Palette with Ctrl/Cmd+Shift+P.
2. Select the Cloud Code: Install or Update Mainframe Modernization Tools command.
3. Verify that the executable file is no longer missing.
4. Open the Command Palette again with Ctrl/Cmd+Shift+P.
5. Select the Developer: Reload Window command.

Inspect the output channel

To troubleshoot other errors not listed in elsewhere in this guide, try inspecting the extension's output channel. To open the output channel, perform the following tasks:

1. Open the Command Palette with Ctrl/Cmd+Shift+P.
2. Select the Output: Show Output Channels command.
3. Select the Cloud Code Mainframe Modernization output channel.