---
title: "Debug on the workstation"
---

# Debug on the workstation

Source-level debugging of COBOL on the workstation with GnuCOBOL and GDB, debugging the step a JCL job runs with its data, CALLed subprograms, the COBOL Files view, and launch configurations from the gnucobol-debug extension.

**Verification state:** **verified on Linux** (Ubuntu 24.04) with GnuCOBOL 3.1.2 and GDB 15.1 on the payroll sample and fixture programs; stopping at breakpoints, values, stepping, the step debug of a payroll job and the COBOL Files view were checked in the running app. Conditional breakpoints, set value and the memory view have not been exercised in the running app. **Not verified on Windows** (it needs a POSIX shell) **or macOS** (it needs a signed GDB). Results are GnuCOBOL's; IBM z/OS Debugger is on [Debug on z/OS](https://neuralinverse.com/docs/modules/mainframe/zos-debug/).

## Debug a program

Press **F5** on an open COBOL program. It is compiled for debugging (`cobc -g`) with the project's copybooks, dialect and format, and run with the launch configuration's DD files.

- **Breakpoints** on statements in the program and its copybooks; **conditional breakpoints** written in COBOL (`IN-EMP-ID = 'E00002' AND WS-COUNT > 0`, level-88 names); hit counts.
- **Step** over, into and out by COBOL statement; pause.
- **Call stack** as `PROGRAM/PARAGRAPH` frames, with the PERFORM chain and callers.
- **Variables:** Working-Storage, Local-Storage, Linkage and File Section records with their values (zoned, packed, binary, COMP-5, COMP-1 and COMP-2, edited, alphanumeric), level-88 conditions, and tables by occurrence.
- **Hover and watch** with qualification, subscripts and reference modification.
- **Set value**, checked against the PICTURE.
- DISPLAY output in the Debug Console; the return code; the memory view.

NATIONAL, COMP-6, COMP-X and FLOAT-DECIMAL items are shown as bytes.

## The COBOL Files view

While debugging, the **COBOL Files** view lists each FD and SD with the file it maps to, its organisation, access and open mode, the last FILE STATUS with its meaning, the records read or written (for fixed-length sequential files), and the record area decoded. **Open in Record Viewer** opens the file; **Read the COBOL Files Again** refreshes the view.

![Stopped at a breakpoint in a sample program, with the call stack and the COBOL Files view showing a file's open mode and status.](https://neuralinverse.com/docs-images/modules/mainframe/cobol-files-view.webp)

## Debug the step a job runs

As z/OS Debugger debugs a batch step, with the step's own data:

1. Run **Debug JCL Step with GnuCOBOL...** (Ctrl+Alt+D, Ctrl+Option+D on macOS), click the **Debug Step** code lens on an EXEC of a project program, or choose **Debug This Step** in the job editor.
2. Pick the step. The steps before it run first, as usual.
3. The chosen step runs under the debugger with exactly the DD files, PARM, SYSIN and environment the runner gives it. Debug JCL Step shows PARM-LEN and PARM-TEXT.
4. Its DISPLAY output and RC become the step's SYSOUT and RC.
5. When the session ends with steps left, choose **Run Remaining Steps** or **End the Job**.

![Debug JCL Step with GnuCOBOL asking which step of a sample job to debug; the steps before it run first.](https://neuralinverse.com/docs-images/modules/mainframe/debug-step-picker.webp)

Programs the step CALLs are debugged too: they are built as debug modules (`cobc -m -g`) and loaded through COB_LIBRARY_PATH, with breakpoints set before load, step into a CALL, step out, and the stack across programs. A debug build is reused while unchanged. A step whose program CALLs subprograms has not been exercised in the running app.

## Launch configurations from gnucobol-debug

Launch configurations written for the gnucobol-debug extension keep working:

- A `"type": "gdb"` configuration with `cobcargs`, a COBOL `target` or `group` runs with this debugger, unchanged.
- `target`, `arguments`, `cwd`, `env`, `group`, `gdbpath`, `cobcpath` and `cobcargs` (`-free`, `-fixed`, `-fformat=`, `-std=`, `-I`) are translated.
- `coverage`, `gdbtty`, `verbose` and unknown attributes run with a warning naming each.
- `docker`, attach, `pid` and `remoteDebugger` stop with an error.
- A Native Debug configuration is left alone, and nothing registers for `gdb` while an installed extension provides it.

The configuration shape is taken from gnucobol-debug's documentation; none of its code is used. Verified by launching a gnucobol-debug `launch.json` on a copy of the payroll sample, and in the running app.