Debugging JVM COBOL Projects

Prerequisites

To debug JVM COBOL projects in Visual Studio Code, you need to install the following software:

The Rocket JVM COBOL extension for Visual Studio Code. Visual Studio Code installs this automatically when you register JVM COBOL support for debugging. Alternatively, you can install this extension from the View > Extensions pane.
A licensed installation of one of the following Rocket Software products, release 9.0 or later:
- Visual COBOL for Eclipse or Enterprise Developer for Eclipse
- Visual COBOL Build Tools or Enterprise Developer Build Tools
- Visual COBOL Development Hub or Enterprise Developer Unix Components
Note: Visual COBOL for Visual Studio, COBOL Server, Enterprise Developer for Visual Studio, and Enterprise Server are not supported.
A minimum of Java 17 installation - You must specify the path to the bin directory of the Java install location within the PATH environment variable. Your licensed Rocket Software product comes with AdoptOpenJDK.
Alternatively, you can specify which Java to use from the settings of the Language Support for Java(TM) by Red Hat extension - see the Java > Jdt > LS > Java: Home setting.
Set the system environment variable JAVA_HOME to the install location of your Java.
Add the path to the bin subfolder within the system PATH environment variable.
Other software requirements - see the product Help of Visual COBOL for Visual Studio or Enterprise Developer for Eclipse for any requirements for compiling JVM COBOL projects.

Register the JVM support

After installing the Rocket JVM COBOL extension, you need to register JVM support inside Visual Studio Code to be able to debug JVM COBOL projects. You only need to do this once:

Invoke the Visual Studio Code Command Palette widget - click Ctrl+Shift+P.
Scroll down or start typing Register JVM COBOL, then click Register JVM COBOL support with Java Language Server (JDT LS).
This adds the COBOL support to the JVM debugger. If not installed, this will also download and install the Rocket JVM COBOL extension for Visual Studio Code.

Alternatively:

The first time you open some JVM COBOL sources in the EXPLORER pane, you receive a message in the bottom right corner of Visual Studio Code:
```
Additional setup is required to build and debug COBOL JVM code.
```
Click Setup in the dialog box to register the JVM support.
Registering JVM support automatically installs the Language Support for Java(TM) extension by Red Hat.

Create a debug launch configuration

Before you can start debugging, you need to create a launch.json file for your sources.

Click Run and Debug in the Activity bar to open the RUN panel.
Click create a launch.json file.
This starts the command palette list showing the available options.
Click COBOL: (JVM).
This creates a launch.json file in your working folder, and opens it in the editor. The file includes one default JVM COBOL debug configuration for launching the current COBOL file.
If necessary, add a configuration suitable for your sources - click Add Configuration in the bottom right corner of the editor.

The following launch configurations are available for debugging JVM COBOL code:

COBOL (JVM): Launch Program - this configuration requires you to specify the main class.

        {
            "type": "coboljvm",
            "name": "Launch COBOL JVM Program",
            "request": "launch",
            "mainClass": ""
        }

COBOL (JVM): Launch Program in Current File - you need to open a program in the editor. The debugger automatically locates the main class in the currently open file.
If there is more than one main method, Visual Studio Code displays a drop-down list, and enables you to select the class to debug.
```
        {
            "type": "coboljvm",
            "name": "Launch Current File",
            "request": "launch",
            "mainClass": "${file}"
        }
```

COBOL (JVM): Launch Program with Arguments Prompt - when you start debugging, Visual Studio Code prompts you to specify any additional arguments to pass to the debugger.

        {
            "type": "coboljvm",
            "name": "Launch with Arguments Prompt",
            "request": "launch",
            "mainClass": "",
            "args": "${command:SpecifyProgramArgs}"
        }

Configurations can have the following parameters:

projectName – the preferred project in which the debugger searches for classes. This is helpful when different projects define classes with identical names. This setting also works when the debugger looks for the specified main class when launching a program. It is required for expressions evaluation.
mainClass – the fully qualified class name (such as com.xyz.MainApp) or the file path to the JVM COBOL program.
args – any command-line arguments to pass to the program.
vmArgs - any additional options and system properties for the JVM (such as -Xms<sizes> -Xmxs<sizes> -Ds<names>=s<values>).
classPaths - the classpaths for launching the JVM. If not specified, the debugger will automatically resolve this using the current project.
cwd - the working directory of the program. Defaults to the current workspace.
env – any additional environment variables for the program.
stopOnEntry - automatically pause the program after launching.

The following configuration is available for attaching and debugging running processes:

COBOL (JVM): Attach to process - in the launch.json file you can specify a configuration to attach to a running process.

        {
            "type": "coboljvm",
            "name": "COBOL (JVM): Attach to process",
            "request": "attach",
            "hostname": "localhost",
            "port": "8001"
        }

The following configuration property is optional for COBOL (JVM): Attach to process:

timeout - the amount of time in milliseconds that Visual Studio Code waits until it attaches to the running process. The default value is 20000 ms (20 seconds).

Note: If the value of timeout is set to zero the timeout will wait forever to attach.

Debugging JVM COBOL projects

To launch debugging:

Set any breakpoints in your programs as required.
In the EXPLORER pane, click Run > Start Debugging.
Debug your project in the usual way.
Check the TERMINAL and PROBLEMS pane for any messages. There is a different debug terminal for each program you debug.