Compiler Setup Guide

Setting Up Your COBOL Development Environment

This guide walks you through setting up everything you need to compile and run the COBOL programs in this book. We primarily use GnuCOBOL, a free, open-source COBOL compiler that runs on Windows, macOS, and Linux. For IBM-specific features (CICS, DB2, IMS), we also cover how to access IBM Z Xplore.

GnuCOBOL (formerly OpenCOBOL) is a free COBOL compiler that translates COBOL to C, then uses GCC to produce native executables. It supports most COBOL 85 features and many COBOL 2002/2014 features.

Windows Installation

Method A: Using the GnuCOBOL Installer (Simplest)

  1. Download the latest GnuCOBOL Windows installer from: - Arnold Trembley's GnuCOBOL builds (search "GnuCOBOL Windows installer") - The GnuCOBOL SourceForge page

  2. Run the installer and accept the default installation path (e.g., C:\GnuCOBOL)

  3. The installer should add GnuCOBOL to your system PATH. Verify by opening Command Prompt: cmd cobc --version

  4. If the command is not found, add GnuCOBOL to your PATH manually: - Open System Properties → Advanced → Environment Variables - Edit the Path variable under System Variables - Add C:\GnuCOBOL\bin (or your installation directory)

Method B: Using MSYS2/MinGW

  1. Install MSYS2 from https://www.msys2.org/

  2. Open the MSYS2 MinGW64 terminal and run: bash pacman -S mingw-w64-x86_64-gnucobol

  3. Verify installation: bash cobc --version

Method C: Using WSL (Windows Subsystem for Linux)

  1. Enable WSL and install Ubuntu from the Microsoft Store

  2. Follow the Linux installation instructions below

macOS Installation

  1. Install Homebrew if not already installed: bash /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

  2. Install GnuCOBOL: bash brew install gnucobol

  3. Verify installation: bash cobc --version

Building from Source

  1. Install prerequisites: bash brew install gcc gmp berkeley-db

  2. Download GnuCOBOL source from SourceForge

  3. Extract, configure, build, and install: bash tar xzf gnucobol-3.x.tar.gz cd gnucobol-3.x ./configure make sudo make install

Linux Installation

Debian/Ubuntu

sudo apt update
sudo apt install gnucobol
cobc --version

Fedora/RHEL/CentOS

sudo dnf install gnucobol
cobc --version

Arch Linux

sudo pacman -S gnucobol
cobc --version

Building from Source (Any Distribution)

# Install prerequisites
sudo apt install build-essential libgmp-dev libdb-dev  # Debian/Ubuntu
# OR
sudo dnf install gcc gmp-devel libdb-devel             # Fedora/RHEL

# Download and build
wget https://sourceforge.net/projects/gnucobol/files/gnucobol/3.2/gnucobol-3.2.tar.gz
tar xzf gnucobol-3.2.tar.gz
cd gnucobol-3.2
./configure
make
sudo make install
sudo ldconfig

Verifying Your Installation

Create a test program hello.cob:

       IDENTIFICATION DIVISION.
       PROGRAM-ID. HELLO-WORLD.

       PROCEDURE DIVISION.
           DISPLAY "Hello, COBOL World!".
           STOP RUN.

Compile and run:

cobc -x hello.cob
./hello

Expected output:

Hello, COBOL World!

If you see this output, your GnuCOBOL installation is working correctly.

Option 2: IBM Z Xplore (For Mainframe-Specific Features)

IBM Z Xplore (formerly IBM zXplore / Master the Mainframe) provides free access to a real z/OS mainframe environment. This is essential for chapters covering CICS, DB2, IMS, and JCL.

Getting Started with Z Xplore

  1. Visit the IBM Z Xplore website and create a free IBM ID

  2. Enroll in the Z Xplore learning system

  3. You will receive credentials for a z/OS system including: - TSO/ISPF access (3270 terminal) - USS (Unix System Services) access - JES2 job submission - DB2 access (in advanced challenges)

  4. Install a 3270 terminal emulator: - Windows: x3270, Mocha TN3270 - macOS: x3270 (via Homebrew: brew install x3270) - Linux: x3270 (sudo apt install x3270) - Cross-platform: Vista tn3270 (web-based)

Limitations

  • Z Xplore access may be time-limited or session-limited
  • Not all enterprise features may be available in the learning environment
  • Some advanced CICS/IMS features require IBM Wazi as a Service (paid)

Option 3: Hercules Mainframe Emulator (Advanced/Optional)

Hercules is an open-source emulator for IBM mainframe hardware. Combined with freely available MVS 3.8j (a 1981-era operating system), you can run a complete mainframe environment on your PC.

When to Use Hercules

  • You want to practice JCL in a real mainframe-like environment
  • You want to understand mainframe hardware concepts
  • You enjoy vintage computing

Basic Setup

  1. Download Hercules from http://www.hercules-390.org/

  2. Download TK4- (a pre-built MVS 3.8j distribution): - Search for "TK4- MVS Turnkey System"

  3. Follow the TK4- quickstart guide to boot MVS

  4. Connect with a 3270 terminal emulator to localhost:3270

Limitations

  • MVS 3.8j uses a 1985-era COBOL compiler (VS COBOL II not available)
  • No DB2, CICS, or IMS support in the free MVS distribution
  • Primarily useful for JCL practice and understanding mainframe concepts

Editor Setup

  1. Install VS Code from https://code.visualstudio.com/

  2. Install the following extensions: - COBOL by Bitlang — Syntax highlighting for COBOL - IBM Z Open Editor — Advanced COBOL editing, includes copybook support - COBOL Lint — Basic static analysis

  3. Configure column markers for fixed-format COBOL: json { "editor.rulers": [6, 7, 11, 72], "editor.tabSize": 4, "[cobol]": { "editor.rulers": [6, 7, 11, 72], "editor.wordWrap": "off" } }

The column markers indicate: - Column 6: Continuation/comment indicator - Column 7: Area A begins - Column 11: Area B begins (common convention) - Column 72: End of program text

Sublime Text

  1. Install Package Control
  2. Install the "COBOL Syntax" package

Vim/Neovim

Add to your .vimrc:

autocmd BufRead,BufNewFile *.cob,*.cbl,*.cpy set filetype=cobol
autocmd FileType cobol set tabstop=4 shiftwidth=4 expandtab
autocmd FileType cobol set colorcolumn=7,8,12,73

Emacs

(add-to-list 'auto-mode-alist '("\\.cob\\'" . cobol-mode))
(add-to-list 'auto-mode-alist '("\\.cbl\\'" . cobol-mode))
(add-to-list 'auto-mode-alist '("\\.cpy\\'" . cobol-mode))

Compiling Programs in This Book

Basic Compilation

# Compile a standalone program
cobc -x program.cob

# Compile with copybook include path
cobc -x -I ../../shared-copybooks program.cob

# Compile with debugging enabled
cobc -x -debug program.cob

# Compile a subprogram (module)
cobc -m subprogram.cob

# Compile main program that calls subprograms
cobc -x main.cob subprogram.cob

Common Compiler Options

Option Description
-x Build an executable
-m Build a dynamically loadable module
-I <path> Add copybook search path
-debug Enable debugging features
-Wall Enable all warnings
-std=cobol85 Enforce COBOL-85 standard
-std=cobol2014 Enforce COBOL-2014 standard
-std=ibm Use IBM compatibility mode
-free Compile in free-format mode
-fixed Compile in fixed-format mode (default)

Running Programs

# Run a compiled program
./program

# Run with runtime debugging
COB_SET_DEBUG=Y ./program

# Run with file status display
COB_FILE_TRACE=Y ./program

Troubleshooting

"cobc: command not found"

  • Ensure GnuCOBOL is in your system PATH
  • On Windows, restart your terminal after installation
  • Try specifying the full path: /usr/local/bin/cobc --version

"error: 'IDENTIFICATION' not recognized"

  • Your file may be in the wrong format. Ensure columns 1-6 are spaces (fixed format)
  • Or compile with -free flag for free-format code

Linker errors about GMP

  • Install the GMP library: sudo apt install libgmp-dev (Debian/Ubuntu)
  • On macOS: brew install gmp

"file status 35" or similar file errors

  • The data file may not exist. Create an empty file first
  • Check file permissions
  • See Appendix B for complete file status code reference

Copybook not found

  • Use -I flag to specify the copybook directory
  • Verify the copybook filename matches the COPY statement exactly
  • GnuCOBOL is case-sensitive on Linux/macOS

What's Next?

With your environment set up, you're ready to begin Chapter 1: The World of COBOL. Turn to part-01-foundations/chapter-01-world-of-cobol/index.md to start your journey.