cobcrun and gdb
The checked build of the last lesson stops at a bad subscript with a message. This lesson is about the two ways to be inside the program when it does something wrong: cobcrun, which runs a module the way the runtime does, and gdb, which stops wherever you tell it and shows the frames that led there.
cobcrun and a module
A module is a COBOL program built as a shared object instead of an executable. cobc -m names the file after the PROGRAM-ID, and a module can be run on its own, which makes it a convenient shape for a small tool:
IDENTIFICATION DIVISION.
PROGRAM-ID. STAMPM.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 WS-NOW PIC X(21).
PROCEDURE DIVISION.
MOVE FUNCTION CURRENT-DATE TO WS-NOW
DISPLAY "STAMPM ran at " WS-NOW(1:8) " " WS-NOW(9:6).
GOBACK.
cobc -m -free -Wall -o STAMPM.so stampm.cob
cobcrun STAMPM
echo $?
STAMPM ran at 20261118 114511
0
cobcrun starts the runtime, resolves the module by name and calls its entry point, which is the same path a CALL from another COBOL program takes. That is why a module that runs under cobcrun is ready for a caller: the two use one loader.
Where cobcrun looks
The module was found because it sits in the current folder. Move it one level down and the same command fails:
mkdir -p lib
mv STAMPM.so lib/
cobcrun STAMPM
echo $?
libcob: error: module 'STAMPM' not found
1
COB_LIBRARY_PATH fixes it without moving the file back. It is a list of folders separated by colons, the way PATH is, and it is read before the default locations:
COB_LIBRARY_PATH=lib cobcrun STAMPM
echo $?
STAMPM ran at 20261118 114511
0
The default locations include the runtime folder of the compiler and the current folder, not the folder of the source. A batch job that keeps its modules in one directory therefore sets COB_LIBRARY_PATH in its step, and the step is the place to read when a job that works on one machine cannot find its module on another.
gdb in batch mode
The program for this part prints an invoice total through a paragraph. Built with -g, the C file that cobc writes carries debug information, and gdb reads the COBOL source lines from it:
IDENTIFICATION DIVISION.
PROGRAM-ID. INVOICE.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 QTY PIC 9(3) VALUE 3.
01 PRICE PIC 9(3)V99 VALUE 12.50.
01 TOTAL PIC 9(6)V99 VALUE 0.
PROCEDURE DIVISION.
MAIN-PARA.
DISPLAY "invoice".
PERFORM TOTAL-LINE
DISPLAY "total " TOTAL.
STOP RUN.
TOTAL-LINE.
COMPUTE TOTAL = QTY * PRICE.
DISPLAY "line " TOTAL.
cobc -x -free -Wall -g -o invoice invoice.cob
./invoice
invoice
line 000037.50
total 000037.50
A breakpoint on line 17 is the line of the paragraph TOTAL-LINE. Six gdb commands, none of them interactive, in one batch run:
gdb -batch -ex 'set disable-randomization off' \
-ex 'break invoice.cob:17' -ex run -ex 'bt 3' \
-ex continue ./invoice
Breakpoint 1 at 0x13dd: file /tmp/l118/invoice.cob, line 17.
invoice
Breakpoint 1, INVOICE_ (entry=0) at /tmp/l118/invoice.cob:17
17 TOTAL-LINE.
#0 INVOICE_ (entry=0) at /tmp/l118/invoice.cob:17
#1 0x00005b5ff4c951dc in INVOICE () at invoice.c:52
#2 0x00005b5ff4c951a0 in main (argc=1, argv=0x7ffc85597908) at invoice.c:34
line 000037.50
total 000037.50
[Inferior 1 (process 692) exited normally]
Three things in that output are COBOL and not C. The breakpoint is set on a .cob line, because the compiler records the COBOL source in the C debug information. The frame is INVOICE_, the C function the compiler makes for the PROCEDURE DIVISION of INVOICE, with the real C function INVOICE above it and main above that. The addresses change from run to run because address randomisation is off only for the program, not for the libraries, which is why the first command turns the warning about it off.
The two DISPLAY lines appear after the backtrace for a reason worth knowing: gdb stops the program before line 17 runs, then continue lets it finish, and the output of the whole run lands below what gdb printed while it was stopped.
A paragraph is not a function
A breakpoint by paragraph name looks tempting and does not work. The obvious guess is that a paragraph becomes a C function named after it, and the guess has a form that a reader can find in the generated C:
gdb -batch -ex 'set disable-randomization off' \
-ex 'break PARAGRAPH_TOTAL__LINE_l_5' -ex run ./invoice
Function "PARAGRAPH_TOTAL__LINE_l_5" not defined.
Make breakpoint pending on future shared library load? (y or [n]) [answered N; input not from terminal]
invoice
line 000037.50
total 000037.50
[Inferior 1 (process 705) exited normally]
The symbol table of the executable explains it. A program of one PROCEDURE DIVISION is one C function, and a paragraph is a label inside it:
nm invoice | grep INVOICE
00000000000011ce t INVOICE
00000000000011de t INVOICE_
000000000000178d t INVOICE_module_init
Three symbols and no paragraph among them. The block of code for TOTAL-LINE is reached by a jump from inside INVOICE_, so gdb can stop on its first source line and nowhere else. In practice that is enough: the COBOL line number is what a reader of the program has in front of them, and bt shows the PERFORM chain that got there, which the C function names do not.
For a program of several programs in one file, or a module called from another, each PROGRAM-ID does get its own pair of C functions, so a breakpoint on ENTRY of the callee is a frame and not a line. Read the frames from the bottom up: main calls the main program, the main program calls the callee, and the statement that failed is in the top frame.
Exercises
- Run the invoice program under gdb with a breakpoint on the COMPUTE line instead of the paragraph header. Which line does gdb name?
- Set COB_LIBRARY_PATH to two folders, one of them empty, and run cobcrun STAMPM from a third. Which folder is searched first?
- Build the module without -m and try cobcrun on the executable. Read the message.
- Use -ex 'info sharedlibrary' in the batch command. Which libcob file is loaded, and from where?
Questions
A new set of questions in a new order every time. Choose one answer for each, then check.
-
What does cobcrun do with a module name?
Answer
Resolves the module on the library path and calls its entry point
cobcrun STAMPM ran the module that cobc -m wrote, through the same loader a CALL uses.
-
The module was moved to lib/. What made cobcrun find it again?
Answer
COB_LIBRARY_PATH=lib in front of the command
COB_LIBRARY_PATH lists the folders searched before the defaults.
-
Which option puts COBOL line numbers into the debug information?
Answer
-g
The breakpoint on invoice.cob:17 exists because the program was built with -g.
-
Why does a breakpoint on PARAGRAPH_TOTAL__LINE_l_5 fail?
Answer
A paragraph is a label inside the C function of the program, not a function
nm shows only INVOICE, INVOICE_ and INVOICE_module_init.
-
What does this program print?
IDENTIFICATION DIVISION. PROGRAM-ID. Q5. DATA DIVISION. WORKING-STORAGE SECTION. 01 N PIC 9(2) VALUE 4. PROCEDURE DIVISION. PERFORM SHOW STOP RUN. SHOW. DISPLAY N.Answer
04
A PIC 9(2) field prints both digits, so the value 4 is 04.
-
What does this program print?
IDENTIFICATION DIVISION. PROGRAM-ID. Q6. DATA DIVISION. WORKING-STORAGE SECTION. 01 A PIC 9(2) VALUE 5. 01 B PIC 9(2) VALUE 0. PROCEDURE DIVISION. IF B = 0 DISPLAY "no" ELSE DISPLAY A END-IF. STOP RUN.Answer
no
B is zero, so the IF takes the first branch.
-
What does this program print?
IDENTIFICATION DIVISION. PROGRAM-ID. Q7. DATA DIVISION. WORKING-STORAGE SECTION. 01 W PIC X(10) VALUE "one two". PROCEDURE DIVISION. DISPLAY W(5:3). STOP RUN.Answer
two
Position 5 is t, and three characters are two.
-
What does this program print?
IDENTIFICATION DIVISION. PROGRAM-ID. Q8. DATA DIVISION. WORKING-STORAGE SECTION. 01 T. 05 T-A PIC 9(2) OCCURS 3 TIMES. 01 I PIC 9(2). PROCEDURE DIVISION. MOVE 7 TO T-A(2). MOVE 9 TO T-A(3). PERFORM VARYING I FROM 2 BY 1 UNTIL I IS GREATER THAN 3 DISPLAY T-A(I) END-PERFORM. STOP RUN.Answer
07 / 09
The loop runs for subscripts 2 and 3 only.
-
What is the exit status of a cobcrun that cannot find its module?
Answer
1
The page shows the failed cobcrun ending with status 1.
-
Why does the checked build of a program read a source line in gdb but not a paragraph?
Answer
Debug information records source lines; a paragraph has no symbol of its own
The line table points at .cob lines, while the paragraph is a label inside one function.
The code on this page was built with cobc (GnuCOBOL) 3.2.0 and run under gdb 16.3 on Alpine Linux 3.24.3 (x86_64) in a Docker container.
Article author: Arthur Isaev