Appendix L: Setting Up GnuCOBOL
Overview
GnuCOBOL is the open-source COBOL compiler used throughout this textbook for hands-on exercises. It translates COBOL source code to C, then compiles the generated C with GCC (or another C compiler) to produce native executables. GnuCOBOL supports the COBOL-85, COBOL 2002, and COBOL 2014 standards, making it suitable for learning virtually all COBOL features outside of IBM-specific platform services (CICS, DB2, JCL).
This appendix provides detailed installation instructions for Windows, macOS, and Linux, followed by IDE configuration, copybook path setup, and a comprehensive troubleshooting guide.
1. Installing GnuCOBOL on Windows
Option A: Windows Installer (Recommended for Beginners)
The simplest way to install GnuCOBOL on Windows is using a prebuilt installer.
- Visit the GnuCOBOL downloads page at https://gnucobol.sourceforge.io/ or https://sourceforge.net/projects/gnucobol/files/
- Download the latest Windows installer package (e.g.,
gnucobol-3.x-windows-installer.exe) - Run the installer, accepting the default installation directory (typically
C:\GnuCOBOL) - The installer adds GnuCOBOL to your system PATH automatically
- Open a new Command Prompt and verify the installation:
cobc --version
Expected output (version number may vary):
cobc (GnuCOBOL) 3.2.0
Option B: MSYS2 (Recommended for Developers)
MSYS2 provides a Unix-like environment on Windows with a package manager that makes installing and updating GnuCOBOL straightforward.
- Download and install MSYS2 from https://www.msys2.org/
- Open the MSYS2 UCRT64 terminal (not the MSYS terminal)
- Update the package database:
pacman -Syu
- If the terminal closes during the update, reopen MSYS2 UCRT64 and run:
pacman -Su
- Install GnuCOBOL and dependencies:
pacman -S mingw-w64-ucrt-x86_64-gnucobol
- Verify the installation:
cobc --version
- To use GnuCOBOL from the standard Windows Command Prompt or PowerShell, add the MSYS2 UCRT64 bin directory to your system PATH:
- Open System Properties > Advanced > Environment Variables
- Edit the system PATH variable
- Add
C:\msys64\ucrt64\bin(adjust if your MSYS2 installation is in a different location)
Option C: Windows Subsystem for Linux (WSL)
WSL provides a full Linux environment within Windows, allowing you to follow the Linux installation instructions.
- Enable WSL by opening PowerShell as Administrator and running:
wsl --install
- Restart your computer when prompted
- Open the installed Linux distribution (Ubuntu by default)
- Follow the Linux installation instructions in Section 3 below
WSL is the most robust option for developers who want a consistent Linux-like experience. VS Code's Remote-WSL extension integrates seamlessly with WSL, allowing you to edit files in Windows while compiling and running in Linux.
2. Installing GnuCOBOL on macOS
Option A: Homebrew (Recommended)
Homebrew is the most convenient package manager for macOS.
- If you do not have Homebrew, install it:
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
- Install GnuCOBOL:
brew install gnucobol
- Verify the installation:
cobc --version
- Homebrew installs GnuCOBOL and all dependencies (GCC, GMP, Berkeley DB) automatically.
Option B: Building from Source
If you need a specific GnuCOBOL version or Homebrew is not an option:
- Install Xcode Command Line Tools (provides the C compiler):
xcode-select --install
- Install dependencies via Homebrew (even when building GnuCOBOL from source, Homebrew is the easiest way to get the dependencies):
brew install gmp berkeley-db@5 automake autoconf libtool
-
Download the GnuCOBOL source tarball from https://sourceforge.net/projects/gnucobol/files/
-
Extract, configure, build, and install:
tar xzf gnucobol-3.2-rc1.tar.gz
cd gnucobol-3.2-rc1
./configure --with-db
make
sudo make install
- Update the dynamic library cache:
sudo ldconfig 2>/dev/null || true
- Verify:
cobc --version
3. Installing GnuCOBOL on Linux
Option A: Package Manager (Recommended)
Most Linux distributions include GnuCOBOL in their package repositories.
Debian / Ubuntu / Linux Mint:
sudo apt update
sudo apt install gnucobol
Fedora:
sudo dnf install gnucobol
Red Hat Enterprise Linux / CentOS / Rocky Linux:
On RHEL 8+ and derivatives, GnuCOBOL may be in the EPEL repository:
sudo dnf install epel-release
sudo dnf install gnucobol
Arch Linux:
sudo pacman -S gnucobol
openSUSE:
sudo zypper install gnucobol
After installation, verify:
cobc --version
Option B: Building from Source (Linux)
If your distribution's package is outdated or you need a specific version:
- Install build dependencies:
Debian/Ubuntu:
sudo apt install build-essential libgmp-dev libdb-dev automake autoconf libtool
Fedora/RHEL:
sudo dnf install gcc make gmp-devel libdb-devel automake autoconf libtool
- Download the source:
wget https://sourceforge.net/projects/gnucobol/files/gnucobol/3.2/gnucobol-3.2-rc1.tar.gz
- Extract, configure, build, and install:
tar xzf gnucobol-3.2-rc1.tar.gz
cd gnucobol-3.2-rc1
./configure
make
sudo make install
sudo ldconfig
- Verify:
cobc --version
4. IDE Setup: Visual Studio Code
Visual Studio Code (VS Code) is recommended as the primary editor for this textbook. Its extension ecosystem provides COBOL syntax highlighting, column rulers for fixed-format layout, and integrated terminal for compilation and execution.
Step 1: Install VS Code
Download VS Code from https://code.visualstudio.com/ and install it for your platform.
Step 2: Install COBOL Extensions
Open VS Code and install the following extensions from the Extensions panel (Ctrl+Shift+X or Cmd+Shift+X):
-
COBOL by Broadcom (extension ID:
broadcommfd.cobol-language-support) -- Provides syntax highlighting, code navigation, copybook resolution, and outline view for COBOL programs. This is the most comprehensive COBOL extension. -
IBM Z Open Editor (extension ID:
ibm.zopeneditor) -- An alternative from IBM that provides COBOL, PL/I, and HLASM support with syntax highlighting and language server features. Use this if you prefer IBM's tooling.
Choose one of the above as your primary COBOL extension. Installing both simultaneously may cause conflicts.
Step 3: Configure Column Rulers
Fixed-format COBOL requires awareness of column positions. Add ruler guidelines to VS Code at the critical column boundaries.
Open VS Code settings (File > Preferences > Settings, or Ctrl+,), search for "rulers", and click "Edit in settings.json". Add the following configuration:
{
"[cobol]": {
"editor.rulers": [
{"column": 6, "color": "#4a4a4a"},
{"column": 7, "color": "#6a6a6a"},
{"column": 11, "color": "#4a4a4a"},
{"column": 72, "color": "#8a2020"}
],
"editor.tabSize": 4,
"editor.insertSpaces": true,
"editor.wordWrap": "off",
"editor.detectIndentation": false
}
}
These rulers mark: - Column 6: End of the sequence number area (columns 1--6) - Column 7: The indicator area (column 7: , -, D, /) - Column 11: End of Area A (columns 8--11); boundary between Area A and Area B - Column 72*: End of the program text area; anything beyond column 72 is ignored by the compiler
The red ruler at column 72 is particularly important -- code beyond this column is silently ignored in fixed-format mode, which can cause subtle bugs if statements are accidentally pushed past this boundary.
Step 4: Configure a Build Task
Create a VS Code build task to compile COBOL programs with a keyboard shortcut.
Create a .vscode directory in your project folder and add a tasks.json file:
{
"version": "2.0.0",
"tasks": [
{
"label": "Compile COBOL (executable)",
"type": "shell",
"command": "cobc",
"args": [
"-x",
"-debug",
"-Wall",
"-fsource-location",
"-I", "${workspaceFolder}/shared-copybooks",
"${file}"
],
"group": {
"kind": "build",
"isDefault": true
},
"problemMatcher": {
"owner": "cobol",
"fileLocation": ["relative", "${workspaceFolder}"],
"pattern": {
"regexp": "^(.+):(\\d+):\\s+(error|warning):\\s+(.+)$",
"file": 1,
"line": 2,
"severity": 3,
"message": 4
}
}
},
{
"label": "Compile COBOL (module)",
"type": "shell",
"command": "cobc",
"args": [
"-m",
"-debug",
"-Wall",
"-fsource-location",
"-I", "${workspaceFolder}/shared-copybooks",
"${file}"
],
"group": "build"
}
]
}
Press Ctrl+Shift+B (or Cmd+Shift+B on macOS) to compile the currently open COBOL file. Compilation errors appear in the VS Code Problems panel.
Step 5: Configure a Launch Task (Optional)
For integrated debugging with GDB, create a .vscode/launch.json file:
{
"version": "0.2.0",
"configurations": [
{
"name": "Run COBOL Program",
"type": "cppdbg",
"request": "launch",
"program": "${fileDirname}/${fileBasenameNoExtension}",
"args": [],
"stopAtEntry": false,
"cwd": "${fileDirname}",
"environment": [
{
"name": "COB_LIBRARY_PATH",
"value": "${workspaceFolder}/shared-copybooks"
}
],
"MIMode": "gdb"
}
]
}
5. Configuring Include Paths for Shared Copybooks
This textbook uses a shared-copybooks/ directory at the project root to store copybook members shared across multiple chapters and exercises. The GnuCOBOL compiler must be told where to find these copybooks.
Command-Line Configuration
Use the -I option to specify the copybook search path:
cobc -x -I /path/to/learning-cobol-programming/shared-copybooks program.cob
Multiple include directories can be specified:
cobc -x -I ../shared-copybooks -I ../part-05-enterprise-data-access/copybooks program.cob
Environment Variable Configuration
Set the COB_COPY_DIR environment variable to specify a default copybook search directory:
Linux / macOS:
export COB_COPY_DIR=/path/to/learning-cobol-programming/shared-copybooks
Add this line to your ~/.bashrc or ~/.zshrc for persistence.
Windows (Command Prompt):
set COB_COPY_DIR=C:\ClaudeTextBooks\learning-cobol-programming\shared-copybooks
Windows (PowerShell):
$env:COB_COPY_DIR = "C:\ClaudeTextBooks\learning-cobol-programming\shared-copybooks"
To make the setting permanent on Windows, add it as a system environment variable through System Properties > Advanced > Environment Variables.
6. Verifying Your Installation
After installing GnuCOBOL and configuring your editor, verify everything works by compiling and running a test program.
Create a file named verify-install.cob with the following content:
IDENTIFICATION DIVISION.
PROGRAM-ID. VERIFY-INSTALL.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 WS-DATE.
05 WS-YEAR PIC 9(4).
05 WS-MONTH PIC 9(2).
05 WS-DAY PIC 9(2).
01 WS-TIME.
05 WS-HOUR PIC 9(2).
05 WS-MINUTE PIC 9(2).
05 WS-SECOND PIC 9(2).
05 WS-HUNDREDTH PIC 9(2).
PROCEDURE DIVISION.
MAIN-PARA.
ACCEPT WS-DATE FROM DATE YYYYMMDD.
ACCEPT WS-TIME FROM TIME.
DISPLAY "GnuCOBOL Installation Verified!"
DISPLAY "Date: " WS-YEAR "/" WS-MONTH "/"
WS-DAY
DISPLAY "Time: " WS-HOUR ":" WS-MINUTE ":"
WS-SECOND
DISPLAY "COBOL is ready."
STOP RUN.
Compile and run:
cobc -x -debug -Wall verify-install.cob
./verify-install
On Windows:
cobc -x -debug -Wall verify-install.cob
verify-install.exe
Expected output (date and time will vary):
GnuCOBOL Installation Verified!
Date: 2025/09/15
Time: 14:30:45
COBOL is ready.
If this works, your GnuCOBOL installation is complete and ready for the textbook exercises.
7. Project Directory Structure
The recommended directory structure for working through this textbook is:
learning-cobol-programming/
shared-copybooks/ Copybooks shared across chapters
part-01-foundations/
ch01/ Chapter 1 exercises and examples
ch02/
...
part-02-control-flow/
ch07/
...
...
.vscode/
tasks.json Build tasks
settings.json Editor settings (rulers, etc.)
Each chapter directory should contain the COBOL source files for that chapter's exercises. Compiled executables are generated in the same directory as the source file by default (or in a separate bin/ directory if you specify -o bin/program).
8. Troubleshooting
Problem: "cobc: command not found"
Cause: GnuCOBOL is not in your system PATH.
Solution (Windows):
- If using the installer, rerun the installer and ensure "Add to PATH" is checked
- If using MSYS2, add C:\msys64\ucrt64\bin to the system PATH
- Open a new terminal after changing PATH (existing terminals do not see PATH changes)
Solution (macOS/Linux):
- If installed via package manager, verify with which cobc
- If built from source, the default install location is /usr/local/bin/. Ensure /usr/local/bin is in your PATH
- Run export PATH=/usr/local/bin:$PATH and add it to your shell profile
Problem: "error: 'gmp.h' file not found" during source build
Cause: The GNU Multiple Precision Arithmetic Library (GMP) development headers are not installed.
Solution:
- Debian/Ubuntu: sudo apt install libgmp-dev
- Fedora/RHEL: sudo dnf install gmp-devel
- macOS: brew install gmp
Problem: "cannot find -ldb" during source build
Cause: The Berkeley DB library is not installed.
Solution:
- Debian/Ubuntu: sudo apt install libdb-dev
- Fedora/RHEL: sudo dnf install libdb-devel
- macOS: brew install berkeley-db@5
- If Berkeley DB is not available, configure with ./configure --without-db (ISAM file support will be limited)
Problem: Copybook not found ("COPY 'ACCOUNT-RECORD' not found")
Cause: The compiler cannot locate the copybook file in its search path.
Solution:
- Use the -I option: cobc -x -I ../shared-copybooks program.cob
- Verify the copybook file exists and has the correct name and extension
- GnuCOBOL searches for copybooks with several extensions: .cpy, .cob, .cbl, .COB, .CBL, and no extension. Ensure your copybook uses one of these
- Check for case sensitivity on Linux/macOS (file system is case-sensitive)
Problem: "libcob.so: cannot open shared object file"
Cause: The GnuCOBOL runtime library is not in the dynamic linker's search path.
Solution (Linux):
sudo ldconfig
If GnuCOBOL was installed to /usr/local, add the library path:
echo "/usr/local/lib" | sudo tee /etc/ld.so.conf.d/gnucobol.conf
sudo ldconfig
Solution (macOS): Homebrew installations handle this automatically. For source builds:
export DYLD_LIBRARY_PATH=/usr/local/lib:$DYLD_LIBRARY_PATH
Problem: Column 72 truncation -- code appears correct but does not compile
Cause: In fixed-format mode, the compiler ignores everything after column 72. If a statement extends beyond column 72, part of it is silently ignored, causing syntax errors.
Solution:
- Enable the column 72 ruler in VS Code (see Section 4, Step 3)
- Check line lengths with: awk 'length > 72' program.cob
- Use continuation (hyphen in column 7 of the next line) or restructure the statement
- Consider using free-format (-free option) if column management is too cumbersome
Problem: "S0C7 equivalent" -- runtime error on arithmetic with non-numeric data
Cause: A numeric field contains non-numeric data (spaces, special characters) when used in arithmetic. This is the GnuCOBOL equivalent of the mainframe S0C7 ABEND.
Solution:
- Use IF field IS NUMERIC to validate data before arithmetic
- Initialize all numeric working-storage items with VALUE clauses
- Check input data for format errors before processing
- Compile with -debug to get a more detailed error message with source location
Problem: Different SORT order between GnuCOBOL and mainframe
Cause: GnuCOBOL runs on ASCII platforms where the collating sequence differs from EBCDIC. See Appendix J for details.
Solution: - Use the COLLATING SEQUENCE clause on the SORT statement - Define an EBCDIC alphabet in SPECIAL-NAMES if mainframe-compatible sort order is required - Be aware that this only affects character-based sorts; numeric sorts are unaffected
Problem: "No such file or directory" when running CALL'd subprograms
Cause: The dynamically loaded module for the called subprogram cannot be found.
Solution:
- Set the COB_LIBRARY_PATH environment variable to include the directory containing the compiled module
- Ensure the subprogram was compiled with -m (not -x)
- Verify the module file exists with the correct name (case-sensitive on Linux/macOS)
- The module name must match the PROGRAM-ID in the subprogram
Problem: Compilation warning "implicit definition of function"
Cause: The generated C code references a function that the C compiler does not recognize, typically due to a missing C library or header.
Solution:
- Ensure all GnuCOBOL dependencies are installed (GMP, Berkeley DB, ncurses)
- If building from source, verify that ./configure completed without errors
- Reinstall GnuCOBOL if dependencies were installed after GnuCOBOL
Problem: SCREEN SECTION programs do not work correctly
Cause: SCREEN SECTION requires the ncurses library (or PDCurses on Windows), which may not be installed.
Solution:
- Debian/Ubuntu: sudo apt install libncurses-dev
- Fedora/RHEL: sudo dnf install ncurses-devel
- macOS: ncurses is included with Xcode Command Line Tools
- Windows (MSYS2): pacman -S mingw-w64-ucrt-x86_64-pdcurses
Problem: Programs compile but produce no output or immediate termination
Cause: Common causes include STOP RUN missing from the PROCEDURE DIVISION, an error in file processing that is not checked (no FILE STATUS checking), or an uninitialized flag variable causing the main processing loop to exit immediately.
Solution:
- Verify STOP RUN is present at the end of the main program logic
- Add FILE STATUS checking after every OPEN, READ, WRITE, and CLOSE
- Initialize all flag variables with VALUE clauses
- Compile with -ftrace to see which paragraphs are entered and in what order
9. Keeping GnuCOBOL Updated
Package Manager Updates
Homebrew (macOS):
brew update && brew upgrade gnucobol
Debian/Ubuntu:
sudo apt update && sudo apt upgrade gnucobol
MSYS2 (Windows):
pacman -Syu mingw-w64-ucrt-x86_64-gnucobol
Source Builds
Monitor the GnuCOBOL project page at https://sourceforge.net/projects/gnucobol/ for new releases. Download the new source, and repeat the configure/make/make install process. The new version will replace the previous installation.
10. Additional Resources
- GnuCOBOL FAQ: https://gnucobol.sourceforge.io/faq/index.html -- Frequently asked questions covering installation, compatibility, and common issues
- GnuCOBOL Programmer's Guide: Available from the project's SourceForge page; provides complete documentation of all compiler options, language features, and runtime configuration
- GnuCOBOL Discussion Forum: https://sourceforge.net/p/gnucobol/discussion/ -- Community forum for asking questions and sharing solutions
- VS Code COBOL Extension Documentation: Available in the VS Code Marketplace entry for each extension; provides configuration details and feature descriptions