Getting Started

Enterprise COBOL for z/OS only runs on a mainframe, so most readers cannot run it at their desk. GnuCOBOL is a free compiler that runs on Linux, macOS, Windows and other systems, and it accepts the same fixed-format, IBM-compatible syntax that the examples of this reference use. That is why every portable example of the section is compiled and run with GnuCOBOL 3.2, and why code that only exists on z/OS (JCL, EXEC SQL, EXEC CICS, VSAM utilities) is labelled "z/OS; not run here" and checked against IBM’s manuals instead.

GnuCOBOL is not Enterprise COBOL. It translates COBOL to C and lets a C compiler produce the machine code (see How cobc turns a source into a program), it runs on ASCII machines unless told otherwise, and it has its own extensions and its own dialect files. Where the two differ in a way that matters to a beginner this page says so (GnuCOBOL versus Enterprise COBOL for a beginner), and Compilers and Dialects covers the full picture.

Where the books this section draws on are outdated: Taulli’s Modern Mainframe Development (2022) presents OpenCobolIDE as the personal-computer environment. That IDE is unmaintained; the current route is GnuCOBOL 3.2 with a general editor such as Visual Studio Code (see Modern Tooling: VS Code and Zowe). The book also sends the learner to IBM’s former 180-day free z/OS access, which has been replaced by IBM Z Xplore (see Free ways to try z/OS).

GnuCOBOL 3.2 was released on 28 July 2023 and is, at the date of this page, still the newest release; the project’s download directory at ftp.gnu.org lists nothing newer. Check which version a package gives you before relying on a feature: cobc --version prints it.

On Debian and Ubuntu the plain gnucobol package is only a dependency package for "the default GnuCOBOL", and a gnucobol4 package also exists. Do not install gnucobol4: it is a snapshot of an unreleased 4.0 branch from 2020 (version 4.0~early~20200606), not a newer GnuCOBOL than 3.2. Naming gnucobol3 explicitly avoids the ambiguity.

Building from the release tarball is the same on every Unix-like system. This is the recipe used to produce the compiler that ran every example of this page, inside a Debian container:

Source: GnuCOBOL Manual: Getting started

ldconfig makes the new libcob shared library visible to the loader on Linux; on macOS it is not needed. cobc --version must print cobc (GnuCOBOL) 3.2.0 (the third number is the patch level, not a fourth release).

The "Built" line is the date of the local build and the "Packaged" line is the release date of the tarball. cobc -i prints more: the C compiler it will call, the library path and the directory of the dialect configuration files.

A COBOL program has up to four divisions; the smallest useful one needs only IDENTIFICATION DIVISION (to name it) and PROCEDURE DIVISION (to do something). The classic layout puts division headers, section names and paragraph names in Area A (columns 8 to 11) and statements in Area B (column 12 onwards); column 7 is the indicator area, where an asterisk makes the whole line a comment, and columns 73 to 80 are ignored. This is fixed reference format, the format of every example of the section except where a page says otherwise.

Source: GnuCOBOL Manual: Hello, world!

PROGRAM-ID names the program; DISPLAY writes its operands to standard output; STOP RUN ends the run unit and returns control to the operating system. Save it as hello.cob, compile it and run it:

The same program in free format has no columns: a line starts anywhere, and a comment starts with *> (which may follow code on the same line). It must be compiled with -free:

Source: GnuCOBOL Manual: Source format

Free format is part of the standard since COBOL 2002, but the examples of the section use fixed format, the classic mainframe layout with the column rules above, so that they run unchanged on both compilers (whether a given Enterprise COBOL release accepts free format is not claimed here; check its Language Reference). The format can also be chosen by name with -fformat=free and -fformat=fixed, and -free is the short form of the first. GnuCOBOL 3.2.0 additionally recognised the free-format source above without any option and printed note: free format detected; the manual still says that -free is required, so pass it. Feeding free-format source to the fixed-format reader is the usual cause of a wall of "invalid indicator" errors (see Reading cobc error messages).

cobc is a driver, not a machine-code compiler. It reads the COBOL source, expands COPY and REPLACE, parses the program, checks it against the chosen dialect and translates it to a C file; it then runs the system’s C compiler on that file and links the result against libcob, GnuCOBOL’s run-time library, which implements files, DISPLAY and ACCEPT, decimal arithmetic, intrinsic functions and the loading of called programs. The C compiler is why a GnuCOBOL installation needs GCC, Clang or another C compiler, and why a C programmer can call and be called from COBOL (see C Getting Started and the section’s interoperability page).

Figure: the GnuCOBOL pipeline from a .cob source to an executable or a module, with the cobc option that stops or changes each stage.

Each stage can be observed. cobc -v prints the commands it runs, which shows the C compiler call and the link against libcob:

Source: GnuCOBOL Manual: Compile

The temporary file names, the C compiler and its flags depend on the machine. cobc -E stops after the preprocessor and writes the expanded source to standard output (with COPY members included), and cobc -C stops after the translation and leaves hello.c (with two .h files next to it) for inspection. Both are useful when a COPY or REPLACING does not do what was expected.

The options of this page’s examples, and the ones used again by later pages, are these. The authoritative list is cobc --help and the manual’s Compiler options chapter.

Source: GnuCOBOL Manual: Compiler options

Make -Wall a habit: the Circulation examples of the whole section compile with cobc -x -Wall and must print nothing. Enterprise COBOL has no equivalent command line; its compiler options are set on the CBL/PROCESS statement or the JCL procedure that compiles the program (see JCL for COBOL Programmers).

The first Circulation program is the greeting at the library desk: it asks for a member’s name with ACCEPT and displays a welcome. It introduces the structure that every later program has: a DATA DIVISION with a WORKING-STORAGE SECTION that declares the variables (01 is a level number, PIC X(30) a 30-character alphanumeric field), a PROCEDURE DIVISION with a named paragraph, and STOP RUN.

Source: GnuCOBOL Manual: Hello, world!

DISPLAY ... WITH NO ADVANCING leaves the cursor on the prompt line; ACCEPT reads one line from standard input into the field, padding it on the right with spaces (a longer line is truncated to 30 characters); FUNCTION TRIM removes the leading and trailing spaces of a field so the greeting does not contain 30-character padding. The continuation of the second DISPLAY needs no special character: a statement simply continues on the next line, and only a nonnumeric literal broken across lines needs the continuation indicator of Reference Format: Fixed and Free. Compile it and run it with the name typed on the keyboard, or piped in as here:

Because the name arrives on a pipe there is no echo of the typed text, which is why the prompt and the greeting share a line; at a terminal the typed name and the newline appear in between. ACCEPT and DISPLAY and their variants are covered on ACCEPT, DISPLAY and Console I/O. The name is not validated against MEMBMAST yet: reading that file by member number comes with Sequential Files, and the record layouts that every later Circulation program shares are introduced with The DATA DIVISION and Level Numbers and kept in copybooks (Copybooks and REPLACE).

GnuCOBOL’s diagnostics follow the GCC format: file:line: severity: text, followed by the source line with a few lines of context and a > marker. The severities are error (no output is produced and cobc exits with status 1), warning (output is produced; the bracketed tag, such as [-Wtyping], is the option that enabled it) and note (more information about the previous message). The line number is the line of the source file as typed, with COPY members shown by their own file name and line. Four situations cover most beginner errors.

An undefined name and a type mismatch. This program is deliberately wrong. It misspells the field in the greeting and moves a number into an alphanumeric field:

Source: GnuCOBOL Manual: Warning options

The error comes first and names the misspelt identifier. The warning (from -Wall, which includes -Wtyping) and the note tell where the field was declared. Note what is missing: nothing is said about the IF that has no END-IF, because a period is allowed to end it (the next pitfall).

An unknown verb. A misspelt statement name is reported as a syntax error at the first token that does not fit, and the note says what the compiler took it for:

The stray period that compiles cleanly. The following program is deliberately wrong and, worse, produces no message at all with -Wall. The period after STOP RUN ends the IF statement, so DISPLAY "Done" is part of the IF, not a statement after it:

With a name, nothing at all is printed (the first command’s output is empty: "Done" is skipped); with an empty line, both messages appear. The cure is the scope terminator: write END-IF where the condition ends and keep the period only at the end of a paragraph. This is the best-known COBOL pitfall and is treated on Conditions: IF and EVALUATE.

Text beyond column 72, and free format in a fixed-format reader. In fixed format everything after column 72 is ignored. A long line therefore loses its tail, and a nonnumeric literal that is cut that way is reported as unterminated. Here a DISPLAY with a long literal and a STOP RUN all on one line (deliberately wrong) gives:

Free-format source given to the fixed-format reader fails differently, because the first character of each line lands in the indicator column. Here hellofree.cob is compiled with -std=cobol85, which forces fixed format:

Only the first two of the seven errors are shown. The letters in the messages are the seventh characters of the lines (L in "HELLOFREE", F in "IDENTIFICATION"). When an error report lists one such message per line, check the format first, and pass -free or move the code to column 8.

A few habits make errors easier to find: fix the first error before looking at the rest, because one mistake often causes several messages; read the lines above the reported one (a missing period or a missing END-IF is usually reported at the next statement); and compile with -Wall from the first line written. IBM’s compiler reports the same problems with message numbers of the form IGYxxnnnn-S (severity I, W, E, S or U), listed in the Enterprise COBOL for z/OS Messages and Codes.

The differences that surface on the first day:

Source: IBM Enterprise COBOL for z/OS 6.5 documentation

The mainframe column is covered on The Mainframe Environment Primer.

GnuCOBOL runs the language, but the data sets, JCL, VSAM, Db2 and CICS parts of the section need a real z/OS system, and the mainframe pages of this reference are written for one. Two free routes exist. Both require the reader to register personally with the provider; nothing on this site creates or uses an account.

In both cases the system has a different set of installed products and options from a production shop, so the JCL procedure names and data set names on the Circulation pages are placeholders (USERID.CIRC.BOOKMAST) that have to be adapted. Where the book is outdated: Taulli’s Zowe examples use the version 1 command-line syntax with old Node.js and Java prerequisites; the current Zowe is the 3.x line, so follow the installation page of the Zowe documentation, not the book.

A minimal edit-compile-run cycle for the rest of the reference, for any file in this section:

-I. lets COPY BOOKREC find BOOKREC.cpy in the same directory. If the program is a module or subprogram, use cobc -m and cobcrun, or name all sources on the cobc -x line. If the program asks for input, redirect it from a file or a pipe. When something is wrong, read the first error, then the line above it.