Attach to Process

Important:

This functionality requires a licensed version of a Rocket Enterprise Developer product on the same machine. See Installation for details.
The following information applies to native COBOL code and to PL/I code.

You can debug a running application in one of the following ways:

Create a launch configuration to attach to the running process
Create a launch configuration to launch the debugger and waiting for a debuggable attachment

Attach to a running process

You can attach to and debug applications as running processes:

Ensure the application sources are stored on your local machine. Open the folder that contains the source files in Visual Studio Code.

Click Run > Start Debugging.

Select the configuration you want to use, if prompted. This creates a launch.json inside a .vscode subfolder in the folder that contains your sources. The launch.json includes two default configurations - one for launching an application, and the other one for attaching to a process. For example:

        {
            "type": "cobol",
            "request": "attach",
            "name": "COBOL (native): Attach to process",
            "processId": "${command:pickProcess}"
        },

For PL/I, this is respectively:

        {
            "type": "pli",
            "request": "attach",
            "name": "PL/I: Attach to process",
            "processId": "${command:pickProcess}"
        }

In the Activity bar, click to open the Run panel.
Select the attach configuration, COBOL (native): Attach to process or PL/I: Attach to process, respectively, from the configuration launcher, and click (Start Debugging).
This opens the Attach to process widget.
Start typing the name of the executable you want to debug, and then select it.

Wait for a debuggable attachment

Ensure the application sources are stored on your local machine. Open the folder that contains the source files in Visual Studio Code.
Click Debug > Start Debugging.
This creates a launch.json inside a .vscode subfolder in the folder that contains your sources, and opens the file in the editor.
Click Add Configuration in the bottom right corner.
This opens a pop-up with the available configurations.

Use the arrow keys to select the COBOL: Wait for attachment or PL/I: Wait for attachment configuration, and add it to the launch.json file.

For COBOL this is:

        {
            "type": "COBOL",
            "request": "launch",
            "name": "COBOL (native): Wait for attachment",
            "waitForAttachment": {options}

        }

Where the supported options are:

any - Waits for and then attaches to the next COBOL program that calls CBL_DEBUGBREAK, or is launched with the COBSW environment variable set to +A.

        {
            "type": "COBOL",
            "request": "launch",
            "name": "COBOL (native): Wait for attachment",
            "waitForAttachment": {
                "any": {}
            }

        }

directory - Waits for and then attaches to the next COBOL program that is launched with its working directory set to either the folder specified, or a subfolder of it.

        {
            "type": "COBOL",
            "request": "launch",
            "name": "COBOL (native): Wait for attachment",
            "waitForAttachment": {
                "directory": "pathtodirectory"
            }

        }

id - Waits for and then attaches to the next COBOL program which calls CBL_DEBUG_START with the identifier you specify in the ID field as an argument. When using the id option the debugger always returns to the waiting state when the program being debugged exits. For example:
```
        {
            "type": "COBOL",
            "request": "launch",
            "name": "COBOL (native): Wait for attachment",
            "waitForAttachment": {
                "id": "myid"
            }

        }
```

returnToWait - Only supported with the any and directory options. Optional. Returns the debugger to a waiting state when the program being debugged exits. For example:

        {
            "type": "COBOL",
            "request": "launch",
            "name": "COBOL (native): Wait for attachment",
            "waitForAttachment": {
                "any": {},
                "returnToWait": true 
            }

        }

For PL/I, this adds the following:

{
    "type": "pli",
    "request": "launch",
    "name": "PL/I: Wait for attachment",
    "waitForAttachment": { 
        "id": "<unique-id>"
    }
}

Where, for PL/I, Visual Studio Code waits for and then attaches itself to the next PL/I program which calls PLITEST with the identifier you specify in the unique-id field as an argument.

Select COBOL (native): Wait for attachment or PL/I: Wait for attachment from the configuration launcher, and click (Start Debugging).
Visual Studio Code starts the debugger and displays a message Waiting for debug connection.