Appendix F: Environment Setup Guide

You do not need a mainframe to learn COBOL. You do need a mainframe to learn production COBOL — the DB2, CICS, JCL, and z/OS-specific aspects that constitute the professional skill set. This appendix covers both: setting up a local environment for practicing core COBOL, and connecting to real or emulated z/OS systems for the full stack.

GnuCOBOL Installation and Configuration

GnuCOBOL (formerly OpenCOBOL) is a free, open-source COBOL compiler that translates COBOL source into C and then compiles the C with GCC. It supports most of the COBOL 85 standard and significant portions of COBOL 2002/2014. It does not support EXEC SQL, EXEC CICS, or z/OS-specific features, but it handles the core language — all four divisions, PERFORM, EVALUATE, STRING, UNSTRING, INSPECT, SORT, file I/O, tables, and intrinsic functions.

GnuCOBOL is the right tool for practicing the COBOL language itself. For practicing DB2, CICS, and JCL, you need a z/OS environment (see later sections).

Windows Installation

Option 1: Pre-built package (recommended)

1. Download the latest GnuCOBOL Windows installer from the GnuCOBOL project page on SourceForge (https://sourceforge.net/projects/gnucobol/).
2. Run the installer. Accept the defaults.
3. The installer adds GnuCOBOL to your PATH. Open a new Command Prompt and verify:

cobc --version

You should see output identifying GnuCOBOL 3.x (or later).

Option 2: MSYS2 / MinGW

# Install MSYS2 from https://www.msys2.org/
# Open MSYS2 MINGW64 terminal
pacman -S mingw-w64-x86_64-gnucobol
cobc --version

Option 3: WSL (Windows Subsystem for Linux)

If you use WSL, follow the Linux instructions below within your WSL distribution. This is often the simplest approach on Windows 10/11.

Linux Installation

Debian/Ubuntu:

sudo apt update
sudo apt install gnucobol
cobc --version

Fedora/RHEL/CentOS:

sudo dnf install gnucobol
cobc --version

From source (for the latest version):

sudo apt install build-essential libgmp-dev libdb-dev
# Download source from https://gnucobol.sourceforge.io/
tar xzf gnucobol-3.2.tar.gz
cd gnucobol-3.2
./configure
make
sudo make install
sudo ldconfig
cobc --version

macOS Installation

brew install gnucobol
cobc --version

If Homebrew does not have the latest version, build from source using the Linux instructions (with Xcode command-line tools installed).

Compiling and Running Programs

# Compile to executable
cobc -x -free -o myprog myprog.cbl

# Compile to module (for CALL)
cobc -m -free subprog.cbl

# Compile and run in one step
cobc -x -free -o myprog myprog.cbl && ./myprog

Key compiler flags:

Configuring for IBM Compatibility

For maximum compatibility with Enterprise COBOL:

cobc -x -fixed -std=ibm -debug -Wall -o myprog myprog.cbl

Use -fixed for traditional column-based COBOL source (which is what you will encounter on the mainframe). Use -std=ibm to enable IBM extensions like COMP-5, reference modification relaxations, and IBM-style file status codes.

File I/O with GnuCOBOL

GnuCOBOL maps COBOL file names to operating system files via environment variables:

# Map DD names to files
export INPUTDD="input.dat"
export OUTPUTDD="output.dat"

# Or use the COB_FILE_PATH variable
export COB_FILE_PATH="/home/user/data"

In the COBOL program:

       SELECT INFILE ASSIGN TO 'INPUTDD'.
       SELECT OUTFILE ASSIGN TO 'OUTPUTDD'.

GnuCOBOL supports SEQUENTIAL, INDEXED (via Berkeley DB or VBISAM), and RELATIVE file organizations. VSAM-specific features (KSDS CI/CA splits, SHAREOPTIONS) are not available.

GnuCOBOL Limitations

GnuCOBOL is excellent for learning and practicing, but be aware of what it does not support:

• No EXEC SQL (no DB2 integration)
• No EXEC CICS (no CICS integration)
• No JCL (programs are invoked from the command line or scripts)
• No EBCDIC (GnuCOBOL uses ASCII; this affects collation and PIC patterns)
• No packed decimal hardware instructions (COMP-3 is emulated in software — functionally correct but performance characteristics differ)
• Some Enterprise COBOL V6 features may not be implemented (check the GnuCOBOL FAQ for the current compatibility matrix)
• No Language Environment (LE) — error handling differs from z/OS

For the exercises in this textbook, GnuCOBOL handles all core COBOL chapters. Chapters on DB2, CICS, and JCL require a z/OS environment.

Zowe CLI for z/OS Access

Zowe is an open-source framework for modern z/OS interaction. Zowe CLI provides command-line access to z/OS services — submitting JCL, transferring files, querying jobs, and interacting with DB2 — from your local workstation. If your organization provides z/OS access, Zowe CLI is the modern way to work with it.

Installation

Zowe CLI requires Node.js 18 or later.

# Install Node.js (if not already installed)
# Download from https://nodejs.org/ or use your package manager

# Install Zowe CLI globally
npm install -g @zowe/cli

# Verify installation
zowe --version

# Install common plugins
zowe plugins install @zowe/db2-for-zowe-cli
zowe plugins install @zowe/cics-for-zowe-cli

Creating a Connection Profile

# Create a z/OSMF profile (interactive)
zowe profiles create zosmf-profile myhost \
    --host mainframe.example.com \
    --port 443 \
    --user YOUR_USERID \
    --password YOUR_PASSWORD \
    --reject-unauthorized false

# Or use Zowe V2 team config (recommended for teams)
zowe config init
# Edit the generated zowe.config.json with your connection details

Common Operations

# Submit JCL from a local file
zowe jobs submit local-file myjob.jcl --vasc

# Submit JCL from a PDS member
zowe jobs submit data-set "MY.JCL.LIB(MYJOB)" --vasc

# View job output
zowe jobs view spool-file-by-id JOB12345 104

# List jobs
zowe jobs list jobs --owner MYUSER --prefix MYJOB*

# Download a data set member
zowe files download data-set "MY.SOURCE.LIB(MYPROG)" -f myprog.cbl

# Upload a local file to a PDS member
zowe files upload file-to-data-set myprog.cbl "MY.SOURCE.LIB(MYPROG)"

# List PDS members
zowe files list all-members "MY.SOURCE.LIB"

# Issue TSO command
zowe tso issue command "LISTDS 'MY.SOURCE.LIB'"

# Issue console command
zowe console issue command "D A,L"

# DB2 query (with DB2 plugin)
zowe db2 execute sql --query "SELECT * FROM SYSIBM.SYSTABLES WHERE CREATOR = 'MYSCHEMA' FETCH FIRST 10 ROWS ONLY"

Zowe Explorer for VS Code

If you use Visual Studio Code, install the Zowe Explorer extension:

1. Open VS Code.
2. Go to Extensions (Ctrl+Shift+X).
3. Search for "Zowe Explorer" and install it.
4. Zowe Explorer provides a graphical tree view of z/OS data sets, USS files, and jobs — you can browse, edit, submit, and view output without leaving VS Code.

This is the closest experience to working on the mainframe you can get from a modern IDE.

Hercules Mainframe Emulator

Hercules is an open-source software implementation of the System/370, ESA/390, and z/Architecture mainframe hardware. It runs on Windows, Linux, and macOS. Combined with a freely available operating system (MVS 3.8j from 1981, or the Turnkey MVS distribution), Hercules gives you a genuine (if ancient) mainframe environment for learning JCL, TSO, and batch processing fundamentals.

What Hercules Can and Cannot Do

Can do: - Run MVS 3.8j (a real, if vintage, OS) - Execute JCL, including JOB/EXEC/DD processing - Run COBOL programs (VS COBOL II era) - Practice TSO/ISPF navigation - Run batch utilities (IEBGENER, IEHPROGM, sort)

Cannot do (with freely available OS): - Run z/OS (requires IBM license) - Run DB2 (requires z/OS) - Run CICS Transaction Server (requires z/OS) - Run Enterprise COBOL V6 (requires z/OS) - Emulate modern z/Architecture features (z16 crypto, etc.)

Installation (Overview)

1. Download Hercules: The SDL Hyperion fork is the actively maintained version. Download from https://github.com/SDL-Hercules-390/hyperion.

On Linux: bash git clone https://github.com/SDL-Hercules-390/hyperion.git cd hyperion ./configure make sudo make install

On Windows, pre-built binaries are available from the releases page.

2. Obtain MVS 3.8j Turnkey System: The Tur(n)key MVS distribution includes a pre-configured MVS 3.8j system with DASD volumes, starter programs, compilers (including a COBOL compiler), and JCL procedures. Download from http://www.bsp-gmbh.com/turnkey/ or similar MVS hobbyist sites.

3. Start Hercules: bash hercules -f mvs.cnf

4. Connect via 3270 terminal emulator: Use x3270 (Linux/Mac), wc3270 (Windows), or any TN3270 emulator. Connect to localhost:3270.

5. IPL (boot) MVS: At the Hercules console, issue ipl 0148 (or whatever the sysres volume address is in your configuration).

Learning Value

Hercules with MVS 3.8j is valuable for developing intuition about the mainframe environment — how JCL works, how TSO works, how the operator console works. The COBOL compiler available (OS/VS COBOL) is ancient, but the JCL concepts are identical to modern z/OS. If you have never touched a mainframe console, spending a weekend with Hercules/MVS is a worthwhile investment.

For learning modern COBOL, DB2, and CICS, use the IBM resources described below instead.

IBM Developer for z/OS (IDz)

IBM Developer for z/OS (IDz), formerly Rational Developer for z (RDz), is IBM's Eclipse-based IDE for mainframe development. It provides:

• COBOL, PL/I, and Assembler editing with syntax highlighting and code completion
• Integrated compilation (submit compile JCL from the IDE)
• Source-level debugging (IBM Debug Tool integration)
• Code coverage analysis
• Refactoring tools
• CICS BMS map editing
• DB2 schema browsing
• JCL editing with validation

Setup Overview

IDz requires a z/OS host connection and appropriate server-side components (RSE — Remote System Explorer daemon). Your z/OS systems programming team must configure the server side.

1. Download IDz from IBM (requires an IBM ID and entitlement — usually through your employer's IBM license).
2. Install the Eclipse-based client on your workstation.
3. Create a connection profile pointing to your z/OS host.
4. Configure RSE, debug, and FTP connections.

IDz is a commercial product included with many IBM z/OS software packages. If your organization has z/OS, check whether IDz is already licensed — it often is.

Alternatives to IDz

If IDz is not available:

• VS Code with Zowe Explorer + COBOL Language Support: Free, open-source. Provides syntax highlighting, code analysis (via the COBOL Language Support extension from Broadcom), and Zowe-based z/OS access. This is increasingly the standard for new mainframe developers.
• IBM Wazi for VS Code: IBM's distribution of VS Code with mainframe extensions. Includes Zowe integration, COBOL language support, and debug capabilities.
• ISPF/PDF (on z/OS): The traditional 3270-based editor. If you have TSO access, ISPF option 2 (edit) is always available. It is not a modern IDE, but it is what generations of COBOL programmers used, and it works.

Free z/OS Resources

IBM Z Xplore (formerly Master the Mainframe)

URL: https://www.ibm.com/it-infrastructure/z/education/zxplore

IBM Z Xplore is IBM's free, self-paced learning program for mainframe skills. It provides:

• Access to a real z/OS system (IBM-hosted, accessed via TN3270 or Zowe)
• Guided challenges covering TSO, ISPF, JCL, COBOL, DB2, and CICS
• Three levels of increasing difficulty (Fundamentals, Concepts, Advanced)
• Digital badges upon completion

This is the single best free resource for learning z/OS. You get a real z/OS userid, real JCL submission, real COBOL compilation, and real DB2 access — all at no cost. The z/OS system is available year-round (not just during competition periods as in the old Master the Mainframe format).

How to use with this textbook: Complete Z Xplore Fundamentals first to get comfortable with TSO, ISPF, and JCL. Then use your Z Xplore z/OS access to practice the DB2 and CICS exercises from the textbook chapters. The Z Xplore environment has the Enterprise COBOL compiler, DB2, and a CICS region available.

IBM zTrial

URL: https://www.ibm.com/z/trials

IBM zTrial provides a time-limited (typically 3 days) z/OS environment for evaluating IBM software products. Available environments include:

• z/OS base system
• z/OS with DB2
• z/OS with CICS
• Wazi as a Service (cloud-hosted z/OS development environment)

zTrial environments come pre-configured with development tools and sample data. They are more powerful than Z Xplore (you get more latitude to install and configure) but are time-limited. Use them for intensive practice sessions on specific topics (e.g., a weekend focused on CICS programming).

IBM Wazi as a Service

URL: Available through IBM Cloud

Wazi as a Service provides a cloud-hosted z/OS environment accessible via VS Code and Zowe. It includes:

• Full z/OS with Enterprise COBOL, DB2, CICS
• Modern IDE integration (VS Code with IBM Wazi extensions)
• CI/CD pipeline integration
• Pay-per-use pricing (free tier available for limited use)

This is the closest thing to "z/OS in the cloud" and represents the future direction of mainframe development environments.

Open Mainframe Project

URL: https://www.openmainframeproject.org/

The Linux Foundation's Open Mainframe Project hosts several relevant open-source projects:

• Zowe: The open-source framework for z/OS (CLI, API Mediation Layer, App Framework)
• COBOL Programming Course: Free course materials for learning COBOL
• COBOL Check: A unit testing framework for COBOL
• Galasa: An integration testing framework for mainframe applications

Additional Learning Resources

Recommended Setup Path

Depending on your situation, follow one of these paths:

Path A: Self-Learner (No z/OS Access)

1. Install GnuCOBOL (this appendix).
2. Work through the core COBOL chapters using GnuCOBOL.
3. Sign up for IBM Z Xplore (free).
4. Complete Z Xplore Fundamentals for TSO/ISPF/JCL basics.
5. Use the Z Xplore z/OS environment for DB2 and CICS chapters.
6. Install VS Code with COBOL Language Support extension for syntax highlighting and code analysis.

Path B: Professional Developer (Organization Has z/OS)

1. Get a TSO userid from your z/OS team.
2. Install Zowe CLI and configure profiles (this appendix).
3. Install VS Code with Zowe Explorer and COBOL Language Support.
4. Request access to development CICS regions and DB2 subsystems.
5. Optionally install IDz if your organization licenses it.
6. Use GnuCOBOL for quick local testing and experimentation.

Path C: Student or Instructor

1. Install GnuCOBOL for local practice.
2. Sign up for IBM Z Xplore (all students).
3. Request IBM Academic Initiative membership (institutions) for expanded z/OS access.
4. Use Wazi as a Service free tier for modern development workflow exposure.
5. Install VS Code with COBOL Language Support — it is what new hires will encounter in the workplace.

Environment Verification Checklist

Before starting the textbook exercises, verify your environment:

Local environment:
[ ] GnuCOBOL installed and cobc --version works
[ ] Can compile and run a simple "Hello, World" COBOL program
[ ] Can compile with -fixed -std=ibm flags
[ ] File I/O works (can read and write sequential files)

z/OS environment (if available):
[ ] Can log in to TSO
[ ] Can navigate ISPF (option 2 for edit, option 3.4 for data set list)
[ ] Can submit JCL and view output
[ ] Can compile a COBOL program with Enterprise COBOL
[ ] Can run a compiled COBOL program via JCL
[ ] DB2 access works (can run SPUFI or a DB2 COBOL program)
[ ] CICS access works (can log in to a CICS region)

Modern tooling (recommended):
[ ] VS Code installed with COBOL Language Support extension
[ ] Zowe CLI installed and configured (if z/OS access available)
[ ] Zowe Explorer extension installed in VS Code (if z/OS access available)

If all local-environment boxes are checked, you can work through the core COBOL portions of every chapter. If the z/OS boxes are also checked, you can work through every exercise in the textbook, including DB2, CICS, and JCL content.