The -t listing

Two kinds of file come out of cobc besides the program: a listing of the source as the compiler read it, and the C it generated. Both are for the day a build disagrees with what the source seems to say.

The -t listing

-t takes the name of the listing file. The program is the one of the previous lesson:

IDENTIFICATION DIVISION. PROGRAM-ID. OPT. DATA DIVISION. WORKING-STORAGE SECTION. 01 WS-N PIC 9(9) VALUE 0. 01 WS-I PIC 9(9) VALUE 0. 01 WS-T PIC 9(18) VALUE 0. PROCEDURE DIVISION. PERFORM VARYING WS-I FROM 1 BY 1 UNTIL WS-I IS GREATER THAN 5000000 ADD WS-I TO WS-T END-PERFORM. DISPLAY "total " WS-T. DISPLAY FUNCTION TRIM("abc"). STOP RUN.

cobc -x -free -t opt.lst -o opt opt.cob
cat opt.lst

GnuCOBOL 3.2.0 opt.cob Wed Nov 18 2026 11:22:34 Page 0001

LINE .....................SOURCE.............................................

000001 IDENTIFICATION DIVISION.
000002 PROGRAM-ID. OPT.
000003 DATA DIVISION.
000004 WORKING-STORAGE SECTION.
000005 01 WS-N PIC 9(9) VALUE 0.
000006 01 WS-I PIC 9(9) VALUE 0.
000007 01 WS-T PIC 9(18) VALUE 0.
000008 PROCEDURE DIVISION.
000009 PERFORM VARYING WS-I FROM 1 BY 1 UNTIL WS-I IS GREATER THAN 5000000
000010 ADD WS-I TO WS-T
000011 END-PERFORM.
000012 DISPLAY "total " WS-T.
000013 DISPLAY FUNCTION TRIM("abc").
000014 STOP RUN.


0 warnings in compilation group
0 errors in compilation group

The header names the compiler, the source and the moment of the build, and the body is the source with a six-digit line number in front of every line. The line numbers are the ones a diagnostic quotes, so a listing and an error message can be read side by side without counting lines.

The last two lines are the summary, and they are the reason a listing belongs in the archive of a release: a build that produced no warning and no error says so in the artefact itself, next to the date and the version of the compiler that made it.

A listing with a warning

A warning does not stop the build and does not shorten the listing: it moves the summary to a second page of the file and repeats the message there. The program puts a three-digit literal into a two-digit field:

IDENTIFICATION DIVISION. PROGRAM-ID. WARN1. DATA DIVISION. WORKING-STORAGE SECTION. 01 WS-SMALL PIC 9(2) VALUE 100. PROCEDURE DIVISION. DISPLAY WS-SMALL. STOP RUN.

cobc -x -free -Wall -t warn.lst -o warn warn.cob
tail -12 warn.lst

warn.cob:5: warning: value size exceeds data size [-Wothers]
3 | DATA DIVISION.
4 | WORKING-STORAGE SECTION.
5 > 01 WS-SMALL PIC 9(2) VALUE 100.
6 | PROCEDURE DIVISION.
7 | DISPLAY WS-SMALL.
000007 DISPLAY WS-SMALL.
000008 STOP RUN.


GnuCOBOL 3.2.0 warn.cob Wed Nov 18 2026 11:22:45 Page 0002

Error/Warning summary:

warn.cob:5: warning: value size exceeds data size

1 warning in compilation group
0 errors in compilation group

The same warning appears three times in the output: on the terminal at the line that caused it, in the numbered source of the listing, and in the summary on page two. The summary is what an auditor reads, because it is the only one of the three that is part of the file that stays.

The C that cobc writes

-C keeps the C file that cobc normally deletes, and it writes three files for one program:

cobc -C -free opt.cob
ls opt.c opt.c.h opt.c.l.h
wc -l opt.c
head -12 opt.c

opt.c opt.c.h opt.c.l.h
234 opt.c
/* Generated by cobc 3.2.0 */
/* Generated from opt.cob */
/* Generated at Nov 18 2026 11:22:45 */
/* GnuCOBOL build date May 23 2026 15:18:55 */
/* GnuCOBOL package date Jul 28 2023 17:02:56 UTC */
/* Compile command cobc -C -free opt.cob */

#include <string.h> /* for memcpy, memcmp and friends */
#define COB_KEYWORD_INLINE inline
#include <libcob.h>

#define COB_SOURCE_FILE "opt.cob"

The header of the file records the compiler, the source, the moment and the exact command line, which is the same information as the header of the listing in a file that a C compiler understands. The program itself is a C function per COBOL paragraph, with every arithmetic statement a call into libcob, which is what the previous lesson measured when -O2 changed the size and not the time.

A build that fails inside the C compiler quotes a line of this file. That is the one case where a COBOL programmer reads C: the line number in the message is the line of the generated file, and the COBOL line it came from is the one in the listing. The next lesson turns to the warnings themselves and the flags that make them a gate.

Exercises

  1. Produce a listing of the message program of the previous lesson and find its OPEN OUTPUT line in it.
  2. Build the warning program without -Wall and compare the summary of the two listings.
  3. Open opt.c and find the C function of the PROCEDURE DIVISION.
  4. Count the lines of opt.c and of opt.c.h. Which is bigger, and why?

Questions

A new set of questions in a new order every time. Choose one answer for each, then check.

  1. What does the -t option of cobc produce?

    Answer

    A listing of the source with line numbers and a summary

    The listing opt.lst showed the numbered source and the summary.

  2. Where does the summary of a listing with a warning stand?

    Answer

    On a second page of the file, under Error/Warning summary

    The tail of warn.lst showed Page 0002 with the summary.

  3. What does -C keep?

    Answer

    The generated C file and its two headers

    The page lists opt.c, opt.c.h and opt.c.l.h.

  4. Which information does the header of the C file carry?

    Answer

    The compiler version, the source, the date and the compile command

    The first six lines of opt.c are exactly that.

  5. What does this program print? IDENTIFICATION DIVISION. PROGRAM-ID. Q5. DATA DIVISION. WORKING-STORAGE SECTION. 01 W-V PIC 9(2) VALUE 99. PROCEDURE DIVISION. DISPLAY W-V. STOP RUN.

    Answer

    99

    A two-digit field shows two digits, and both are in use.

  6. What does this program print? IDENTIFICATION DIVISION. PROGRAM-ID. Q6. DATA DIVISION. WORKING-STORAGE SECTION. 01 W-N PIC 9(3) VALUE 0. 01 W-I PIC 9 VALUE 0. PROCEDURE DIVISION. PERFORM VARYING W-I FROM 1 BY 1 UNTIL W-I IS GREATER THAN 3 ADD W-I TO W-N END-PERFORM. DISPLAY W-N. STOP RUN.

    Answer

    006

    One, two and three add to six.

  7. What does this program print? IDENTIFICATION DIVISION. PROGRAM-ID. Q7. DATA DIVISION. WORKING-STORAGE SECTION. 01 W-A PIC 9(4) VALUE 1234. 01 W-B PIC 9(4) VALUE 0. PROCEDURE DIVISION. MOVE W-A TO W-B. DISPLAY W-B. STOP RUN.

    Answer

    1234

    The value fits the field and the move copies it.

  8. What does this program print? IDENTIFICATION DIVISION. PROGRAM-ID. Q8. DATA DIVISION. WORKING-STORAGE SECTION. 01 W-L PIC X(6) VALUE "LINE". PROCEDURE DIVISION. DISPLAY "[" FUNCTION TRIM(W-L) "]". STOP RUN.

    Answer

    [LINE]

    The trim removes the two spaces of the padding.

  9. Why does a listing belong in the archive of a release?

    Answer

    It records the compiler, the date and the warnings of that exact build

    The header and the summary carry the facts a later reader cannot reconstruct.

  10. When does a COBOL programmer read the generated C?

    Answer

    When the C compiler reports an error in a line of that file

    The C message quotes a line of opt.c, and the listing gives the COBOL line it came from.

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

Banner image