COBOL Debug & Language Support for VS Code

By Heirloom Computing - Modernizing Mainframe Applications

A comprehensive Visual Studio Code extension providing debugging and language support for COBOL, PL/I, BMS, and JCL. This extension enables modern COBOL development workflows with full debugging capabilities, syntax highlighting, and code intelligence.

Part of the Heirloom Computing suite for mainframe modernization and COBOL-to-Java transformation.

Features

🔧 COBOL Debugging

Full Debug Adapter Protocol (DAP) Support: Set breakpoints, step through code, inspect variables
Enhanced Variable Display: View COBOL variable values using Eclipse IDE infrastructure
Variable Value Editing: Double-click variables to edit values in real-time during debugging
Auto-Advance: Automatically positions debugger on first COBOL line (no need to hit continue)
Source Mapping: Debug COBOL source while running compiled Java bytecode using SMAP files
Stack Frame Navigation: Navigate through COBOL call stack with proper source mapping
Variable Inspection: Inspect COBOL variables, groups, and data structures with proper value display

🎨 Language Support

COBOL: Comprehensive syntax highlighting for all COBOL dialects (.cbl, .cob, .cobol, .cpy)
PL/I: Full PL/I language support (.pl1, .pli, .plinc)
BMS: Basic Mapping Support syntax highlighting (.bms)
JCL: Job Control Language syntax highlighting (.jcl, .job, .cntl)

📝 Code Intelligence

Language Server: Semantic analysis, error detection, and code intelligence
Code Snippets: Built-in snippets for common COBOL, PL/I, BMS, and JCL patterns
Go to Definition: Navigate to Java source from COBOL (when available)
Workspace Refresh: Reload COBOL workspace metadata

⚡ Development Workflow

Run & Debug Buttons: One-click run/debug from editor or file explorer
Build Integration: Automatic detection of project build requirements
Multiple Consoles: Support for internal, integrated terminal, or external terminal
Flexible Configuration: Extensive customization options for different project setups

Quick Start

Prerequisites

Java 17+: Required for running the debug adapter and language server
Heirloom Computing COBOL Compiler: Heirloom Computing's COBOL-to-Java transpiler
Built Project: Compiled COBOL programs with generated SMAP files

Installation

Install from VS Code Marketplace: Ctrl+Shift+X → Search "COBOL Debug & Language Support"
Or install from VSIX: code --install-extension vscode-cobol-debug-1.0.0.vsix

Basic Setup

Open COBOL Project: Open your COBOL project folder in VS Code

Configure Debug: Create .vscode/launch.json:

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "cobol",
      "request": "launch",
      "name": "Debug COBOL Program", 
      "program": "${workspaceFolder}/src/main/COBOL/MyProgram.cbl",
      "mainClass": "myprogram",
      "classpath": [
        "${workspaceFolder}/build/libs/*.jar",
        "${workspaceFolder}/build/classes/java/main",
        "${workspaceFolder}/build/generated/src/main/intermediate_java"
      ],
      "smapPath": "${workspaceFolder}/build/generated/src/main/intermediate_java"
    }
  ]
}

Build Project: Ensure your COBOL programs are compiled to Java with SMAP files
Start Debugging: Press F5 or click the debug button

Configuration

Debug Configuration Properties

Property	Type	Description	Default
`program`	string	Path to COBOL source file	Required
`mainClass`	string	Java main class name	Required
`classpath`	string[]	Java classpath entries	`["${workspaceFolder}/build/*/.jar"]`
`smapPath`	string	Directory containing SMAP files	`"${workspaceFolder}/build"`
`javaExecutable`	string	Java command path	`"java"`
`console`	string	Console type (`integratedTerminal`, `internalConsole`, `externalTerminal`)	`"integratedTerminal"`
`stopOnEntry`	boolean	Stop at program entry	`false`
`cwd`	string	Working directory	`"${workspaceFolder}"`
`env`	object	Environment variables	`{}`
`args`	string[]	Program arguments	`[]`
`vmArgs`	string[]	JVM arguments	`[]`

Extension Settings

Configure the extension through VS Code Settings (Ctrl+,):

Debug Settings

cobol.debug.javaPath: Java executable path
cobol.debug.verboseLogging: Enable verbose logging
cobol.debug.autoDetectBuild: Auto-detect build requirements
cobol.debug.enableVariableEditing: Enable variable value editing during debugging
cobol.debug.defaultClasspath: Default classpath patterns
cobol.debug.defaultSmapPath: Default SMAP file location

Language Server Settings

cobol.languageServer.enabled: Enable language server
cobol.languageServer.javaPath: Java path for language server
cobol.languageServer.verboseLogging: Verbose language server logging

Usage Examples

Example 1: Simple COBOL Program Debug

{
  "type": "cobol",
  "request": "launch", 
  "name": "Debug Hello World",
  "program": "${workspaceFolder}/src/HELLOWORLD.cbl",
  "mainClass": "helloworld",
  "classpath": ["${workspaceFolder}/build/libs/ecobol.jar"]
}

Example 2: Advanced Configuration

{
  "type": "cobol",
  "request": "launch",
  "name": "Debug Customer Processor",
  "program": "${workspaceFolder}/src/main/COBOL/CustomerProcessor.cbl", 
  "mainClass": "customerprocessor",
  "classpath": [
    "${workspaceFolder}/build/libs/*.jar",
    "${workspaceFolder}/build/classes/java/main", 
    "${workspaceFolder}/lib/database-driver.jar"
  ],
  "smapPath": "${workspaceFolder}/build/generated/src/main/intermediate_java",
  "args": ["--config", "production.conf"],
  "vmArgs": ["-Xmx2g", "-Denv=production"], 
  "env": {
    "DB_URL": "jdbc:postgresql://localhost:5432/mydb"
  }
}

Example 3: Attach to Running Process

{
  "type": "cobol", 
  "request": "attach",
  "name": "Attach to COBOL Process",
  "host": "localhost",
  "port": 8000,
  "smapPath": "${workspaceFolder}/build/generated/src/main/intermediate_java"
}

Debugging Features

Variable Inspection

The extension provides enhanced variable inspection that shows actual COBOL data values:

Simple Variables: Display current values with proper type information
Group Variables: Expand to show child elements
Arrays: Navigate through array elements
Numeric Variables: Show both display and computational formats

Breakpoints

Line Breakpoints: Set breakpoints directly in COBOL source
Conditional Breakpoints: Break when conditions are met
Temporary Breakpoints: Auto-removed after first hit
SMAP-Mapped Breakpoints: Automatically map COBOL lines to Java bytecode

Step Operations

Step Over: Execute next COBOL statement
Step Into: Step into COBOL paragraph/section calls
Step Out: Complete current paragraph/section
Continue: Run until next breakpoint

Variable Value Editing

The extension supports real-time editing of COBOL variable values during debugging:

How to Edit Variables

Set a breakpoint and start debugging your COBOL program
Navigate to Variables view when execution is paused
Double-click on any variable value to open the inline editor
Type the new value and press Enter to apply changes
Continue debugging with the updated variable value

Supported Variable Types

PIC X (Alphanumeric): Edit string values with automatic length validation
PIC 9 (Numeric): Edit numeric values with format validation
COMP/BINARY: Edit computational fields
Index Variables: Edit COBOL Index variables using proper runtime methods
Array Elements: Edit individual array elements (future enhancement)

Type Validation

The debugger automatically validates new values based on COBOL type definitions:

Numeric fields accept only valid number formats
Alphanumeric fields are validated against PIC clause length restrictions
Invalid values are rejected with clear error messages

Configuration

Variable editing can be controlled via VS Code settings:

{
  "cobol.debug.enableVariableEditing": true
}

Troubleshooting

Common Issues

"Class not found" Errors

Problem: Debug adapter can't find the main class Solution:

Ensure classpath includes compiled Java classes
Verify mainClass matches the generated Java class name (usually lowercase)
Check that the project has been built successfully

"SMAP file not found" Warnings

Problem: Source mapping files missing Solution:

Ensure COBOL compiler generates SMAP files
Verify smapPath points to directory containing .smap files
Check file permissions on SMAP directory

Debugger Doesn't Stop on Breakpoints

Problem: Breakpoints not hitting in COBOL source
Solution:

Verify SMAP files exist and are current
Check that breakpoints are on executable COBOL lines
Ensure debug symbols are enabled in compilation

Variable Values Show as ""

Problem: Variable inspection failing Solution:

Check that ecobol.jar is in classpath
Verify Java version compatibility (Java 17+ recommended)
Enable verbose logging to see detailed error messages

Debug Logging

Enable verbose logging to diagnose issues:

Extension Settings: Set cobol.debug.verboseLogging to true
Launch Configuration: Add "console": "integratedTerminal"
Debug Adapter Log: Check debug-adapter.log in workspace root
VS Code Developer Tools: Help → Toggle Developer Tools → Console tab

Performance Tips

Classpath Optimization: Only include necessary JARs in classpath
SMAP Caching: Keep SMAP files current but avoid rebuilding unnecessarily
JVM Tuning: Use appropriate -Xmx settings for large programs
Working Directory: Set cwd to appropriate directory for file I/O

Extension Development

Building from Source

git clone https://github.com/heirloom-computing/vscode-cobol-debug.git
cd vscode-cobol-debug/vscode-extension
npm install
npm run build
npm run package

Architecture

Debug Adapter: Java-based DAP implementation for COBOL debugging
Language Server: Java-based LSP implementation for COBOL language features
VS Code Extension: TypeScript client orchestrating debug adapter and language server
SMAP Integration: Source mapping between COBOL and Java for debugging

Contributing

Fork the repository
Create feature branch: git checkout -b feature/my-feature
Make changes and add tests
Run tests: npm test
Commit changes: git commit -am 'Add my feature'
Push branch: git push origin feature/my-feature
Create Pull Request

Support

Issues: GitHub Issues
Documentation: Project Wiki
Professional Support: support@heirloomcomputing.com
Website: heirloomcomputing.com

License

This extension is proprietary software owned by Heirloom Computing, Inc. See LICENSE.txt for details.

This software is protected by copyright and other intellectual property laws. Unauthorized reproduction or distribution of this software, or any portion of it, may result in severe civil and criminal penalties, and will be prosecuted to the maximum extent possible under law.

Changelog

1.0.0 - Initial Release

Full COBOL debugging support with DAP
Enhanced variable display using Eclipse IDE infrastructure
Variable value editing with real-time updates and type validation
Auto-advance to first COBOL line
Syntax highlighting for COBOL, PL/I, BMS, JCL
Language server integration
Comprehensive VS Code integration

Happy COBOL Debugging! 🚀

Powered by Heirloom Computing - Your partner in mainframe modernization

COBOL Debug & Language Support by Heirloom Computing

Heirloom Computing

COBOL Debug & Language Support for VS Code

Features

🔧 COBOL Debugging

🎨 Language Support

📝 Code Intelligence

⚡ Development Workflow

Quick Start

Prerequisites

Installation

Basic Setup

Configuration

Debug Configuration Properties

Extension Settings

Debug Settings

Language Server Settings

Usage Examples

Example 1: Simple COBOL Program Debug

Example 2: Advanced Configuration

Example 3: Attach to Running Process

Debugging Features

Variable Inspection

Breakpoints

Step Operations

Variable Value Editing

How to Edit Variables

Supported Variable Types

Type Validation

Configuration

Troubleshooting

Common Issues

"Class not found" Errors

"SMAP file not found" Warnings

Debugger Doesn't Stop on Breakpoints

Variable Values Show as ""

Debug Logging

Performance Tips

Extension Development

Building from Source

Architecture

Contributing

Support

License

Changelog

1.0.0 - Initial Release