From source to executable with cobc
cobc is one command with several jobs, and the flag decides which one it does. -x makes an executable, -c an object file, -m a shared module, and -C stops after the C it generates. Learning which output belongs to which flag is the difference between a build that works and a folder full of files nobody asked for.
This lesson runs each of those on the same small program, looks inside the C the compiler wrote, and then reads the two numbers a build and a run each report: the compiler's exit status and the program's.
One command, three stages
A COBOL build is three programs in a row. cobc reads the COBOL source and writes a C file; the C compiler of the system turns that C into an object file; the linker puts the object together with libcob and writes the executable. The flags of cobc name where the chain should stop.
The program below is the one every command in this lesson works on: four items at 12.25, with the total in a field that has room for five integer digits and two decimals.
IDENTIFICATION DIVISION.
PROGRAM-ID. TOTAL.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 WS-COUNT PIC 9(3) VALUE 4.
01 WS-PRICE PIC 9(3)V99 VALUE 12.25.
01 WS-TOTAL PIC 9(5)V99.
PROCEDURE DIVISION.
COMPUTE WS-TOTAL = WS-COUNT * WS-PRICE.
DISPLAY "total: " WS-TOTAL.
STOP RUN.
An executable with -x
-x is the flag for a program a person starts. The output name comes from -o, or from the source file name without its extension. With -Wall the compiler also reports the warnings of the groups that are off by default, and this program has none.
cobc -x -free -Wall -o total total.cob
./total
echo "status: $?"
total: 00049.00
status: 0
The total has the leading zeros of its picture, which is what DISPLAY does with a numeric field: it prints the stored digits. WS-COUNT * WS-PRICE is exact, because both sides are decimal and the product fits in PIC 9(5)V99.
Objects, modules and C with -c, -m and -C
-c stops after the object file: it is what a Makefile builds when a program is made of several sources. -m writes a shared module that another COBOL program can CALL by name; the lesson on building modules links one. -C stops one stage earlier and keeps the C, together with the two headers the compiler writes beside it.
cobc -c -free -Wall total.cob
cobc -m -free -Wall total.cob
cobc -C -free -Wall total.cob
ls -l total*
-rwxr-xr-x 1 agent agent 19960 Nov 18 05:54 total
-rw-r--r-- 1 agent agent 5364 Nov 18 05:54 total.c
-rw-r--r-- 1 agent agent 787 Nov 18 05:54 total.c.h
-rw-r--r-- 1 agent agent 1664 Nov 18 05:54 total.c.l.h
-rw-r--r-- 1 agent agent 288 Nov 18 05:54 total.cob
-rw-r--r-- 1 agent agent 6760 Nov 18 05:54 total.o
-rwxr-xr-x 1 agent agent 17896 Nov 18 05:54 total.so
Seven files from one source, and only two of them are worth keeping: the source and, for a library, the module. The executable is smaller than the one built with -x in the previous section because the two builds ran with different flags on different days; what matters is which file each flag produces. A build directory usually keeps *.o, *.so and the executable, and a clean target deletes all of them.
The C the compiler wrote
The first seven lines of total.c are a log of the build itself: the compiler version, the source, the date, and the exact command line that produced the file. The rest is C that calls into libcob for every verb.
head -14 total.c
/* Generated by cobc 3.2.0 */
/* Generated from total.cob */
/* Generated at Nov 18 2026 05:54:09 */
/* GnuCOBOL build date May 23 2026 15:18:55 */
/* GnuCOBOL package date Jul 28 2023 17:02:56 UTC */
/* Compile command cobc -C -free -Wall total.cob */
#include <string.h> /* for memcpy, memcmp and friends */
#define COB_KEYWORD_INLINE inline
#include <gmp.h>
#include <libcob.h>
#define COB_SOURCE_FILE "total.cob"
#define COB_PACKAGE_VERSION "3.2"
The gmp.h include is the arbitrary-precision library behind COBOL's decimal arithmetic, and libcob.h declares the runtime functions. The generated C is not a target for editing: a change there is thrown away at the next build. It is a target for reading, and the lesson on the -t listing shows the line map that connects a COBOL statement to its C.
The exit status
cobc returns 0 when it wrote its output and 1 when it failed, which is how make knows to stop. A program reports its own status to the shell, and COBOL sets it with the special register RETURN-CODE: a value moved there before STOP RUN becomes the number the shell reads as $?.
IDENTIFICATION DIVISION.
PROGRAM-ID. STATUS.
PROCEDURE DIVISION.
DISPLAY "about to fail".
MOVE 3 TO RETURN-CODE.
STOP RUN.
cobc -x -free -Wall -o status status.cob
./status
echo "status: $?"
about to fail
status: 3
The line was printed before the status was set, so the output and the exit code are independent. A program that reaches the end of PROCEDURE DIVISION without a STOP RUN also exits 0, and a program that leaves RETURN-CODE alone at the end of STOP RUN exits 0 as well. The lesson on RETURN-CODE uses the same register to report a batch failure to the scheduler.
A syntax check with -fsyntax-only
-fsyntax-only parses and checks a source and writes nothing: no C, no object, no executable. It is the cheapest gate a commit hook can run, and it is what this site runs over every program a lesson shows.
cobc -fsyntax-only -free -Wall total.cob
echo "syntax: $?"
ls total.o
syntax: 0
total.o
Silence is the success message, and the object file in the folder is the one from the earlier -c build, untouched: the check wrote nothing at all.
Exercises
- Build total.cob with -x but no -o. What is the executable called, and what happens when you run cobc -x -free total.cob twice?
- Change the MOVE 3 TO RETURN-CODE to 0, then 255, then 256. Read $? after each run and explain the last one.
- Delete every file whose name starts with total. except the source, then rebuild the executable with one command.
Questions
A new set of questions in a new order every time. Choose one answer for each, then check.
-
Which flag makes cobc write an executable?
Answer
-x
-x builds an executable; -c stops at the object file and -m writes a callable module.
-
Which flag writes a shared module that another COBOL program can CALL?
Answer
-m
-m produces the .so module named after the program, which cobcrun or a CALL statement can load.
-
What does
cobc -fsyntax-onlywrite?Answer
Nothing at all
The flag stops after the checks, so the folder is unchanged whatever the result.
-
What is the exit status of cobc when the source has a syntax error?
Answer
1
cobc returns 1 on a failed build, which is the value make and a shell test read.
-
What does this program print, and what status does the shell see?
IDENTIFICATION DIVISION. PROGRAM-ID. Q1. PROCEDURE DIVISION. DISPLAY "bye". MOVE 2 TO RETURN-CODE. STOP RUN.Answer
bye / status: 2
The DISPLAY line is printed and RETURN-CODE becomes the exit status of the process.
-
What does this program print?
IDENTIFICATION DIVISION. PROGRAM-ID. Q2. DATA DIVISION. WORKING-STORAGE SECTION. 01 A PIC 9(2) VALUE 3. 01 B PIC 9(2) VALUE 4. 01 C PIC 9(3). PROCEDURE DIVISION. COMPUTE C = A * B. DISPLAY C. STOP RUN.Answer
012
C holds three digits and DISPLAY prints all of them, so 12 becomes 012.
-
Which files does
cobc -C -free total.cobwrite?Answer
total.c, total.c.h and total.c.l.h
-C keeps the generated C and writes a global and a local header beside it.
-
Which command builds an executable named
runmefromapp.cob?Answer
cobc -x -free -o runme app.cob
-x is the executable flag and -o names the output, so -o runme app.cob is the pair that works.
-
What is the first line of the compiler output for this program?
IDENTIFICATION DIVISION. PROGRAM-ID. Q3. DATA DIVISION. WORKING-STORAGE SECTION. 01 A PIC 9. PROCEDURE DIVISION. MOVE 1 TO B. DISPLAY A. STOP RUN.Answer
error: 'B' is not defined
B was never declared in the DATA DIVISION, and cobc reports the first use of the name it cannot resolve.
-
What does a program do when it reaches the end of PROCEDURE DIVISION without STOP RUN?
Answer
It ends normally with status 0
Falling off the end of the procedure returns to the caller, and for the main program that is a normal exit.
The code on this page was built with cobc (GnuCOBOL) 3.2.0 and run on Alpine Linux 3.24.3 (x86_64) in a Docker container.
Article author: Arthur Isaev