SuperBOL VSCode Debug

This extension can be used to debug and check the coverage of your COBOL code. It must be used in combination with the SuperBOL VSCode Extension to recognize the COBOL files.

Usage

If you do not already have a configuration, go to the Run and Debug pane (Ctrl + Shift + D),

Click on Show all automatic debug configurations and select Add configuration... and COBOL Debugger.

This will add the necessary configurations to your launch.json file (or create it if needed).

Once you have your debugging configuration (see Debugging configurations), you can launch debugging by pressing F5 while being in the COBOL file you wish to debug.

TODO: screenshots.

Extension settings

These settings are to be modified by going to File > Preferences > Settings

Then select the Extensions submenu and select SuperBOL Debugger.

cobcpath [1]

This is the path to the cobc executable, which will be used to build your application.

Default is cobc.

gdbpath

This is the path to the gdb executable, which will be used to launch the debugger.

Default is gdb.

target

This is the path to your source code, it is relative to the VSCode workspace (or it can be an absolute path). This will be overriden by the target field in the debugging configurations if specified (cf. next section).

Default is ${file}.

cwd

This is the root directory of your project. This will be overriden by the cwd field in the debugging configurations if specified (cf. next section).

Default is ${workspaceRoot}.

display_variable_attributes

Set this to true if you want to display data storages and fields attributes (e.g. size of alphanumerics or digits and scale of numerics).

Default is false.

Debugging configurations

These configurations are to be added in your .vscode/launch.json file. There are two types of configurations: launch and attach. Attach can be local or remote.

launch Configuration

This configuration is used to launch the compiled program with the debugger. This configuration has the following defaults:

{
   "name": "SuperBOL debugger",
   "type": "gdb",
   "request": "launch",
   "target": "${file}",
   "arguments": null,
   "cwd": "${workspaceRoot}",
   "gdbpath": "gdb",
   "cobcpath": "cobc",
   "cobcargs": [
     "-free",
     "-x"
   ],
   "group": [],
   "env": null,
   "coverage": true,
   "verbose": false
}

The minimal configuration is as follow (all missing elements are either using the extension settings value if they exists or the default value given just above):

{
   "name": "SuperBOL debugger",
   "type": "gdb",
   "request": "launch",
}

The items of the configuration have the following effects:

  • target: changes the target to be executed with the debugger;

  • arguments: the arguments that the debugger will pass to the target;

  • cwd: the path to the project root;

  • gdbpath: the path to the gdb executable;

  • cobcpath: the path to the cobc executable [1];

  • cobcargs: the arguments to pass to cobc [1];

  • group: other files in the compilation group (other than target) [1];

  • env: an object containing environment variables

  • coverage: weither to show the coverage of the debugged file;

  • verbose: show the debugger output in the Debug Console view (for debugging only).

attach Configuration

The default configuration is as follow:

{
   "name": "SuperBOL debugger",
   "type": "gdb",
   "request": "launch",
   "target": "${file}",
   "arguments": null,
   "cwd": "${workspaceRoot}",
   "gdbpath": "gdb",
   "cobcpath": "cobc",
   "cobcargs": [
     "-free",
     "-x"
   ],
   "group": [],
   "env": null,
   "coverage": true,
   "verbose": false,
   "pid": null,
   "remoteDebugger": null
}

However this configuration will not work, as either pid or remoteDebugger must have a value. All other values have the same usage as in launch Configuration.

  • pid: The id of the process to attach to in a local attach configuration;

  • remoteDebugger: The address of the gdb server to attach to, with format host:port.

Coverage

If you are running the debugger with a launch request and set coverage to true, and set enable-coverage to true in your task.json file. Once the debugger has stopped running, you will see the coverage status of every line in the PROCEDURE DIVISION.

A red line signifies that the line is never runned.

A green line signifies that the line is runned.