Building modules with cobc -m and -c

A subprogram is compiled once and used by many jobs, and there are two ways to ship it: as a module the runtime loads by name, or as an object file the linker puts inside the executable. This page builds the same subprogram both ways and shows the files and the two errors that come with the choice.

Why a subprogram is not -x

-x asks for an executable, and an executable needs a main program with no parameters. This subprogram has a parameter list, so the request is refused:

IDENTIFICATION DIVISION. PROGRAM-ID. CALLEE. DATA DIVISION. LINKAGE SECTION. 01 L-A PIC 9(5). 01 L-R PIC 9(9). PROCEDURE DIVISION USING L-A L-R. COMPUTE L-R = L-A * 3 GOBACK. END PROGRAM CALLEE.

cobc -x -free -Wall -o x callee.cob

callee.cob:8: error: executable program requested but PROCEDURE/ENTRY has USING clause
6 | 01 L-R PIC 9(9).
7 | PROCEDURE DIVISION USING L-A L-R.
8 > COMPUTE L-R = L-A * 3
9 | GOBACK.
10 | END PROGRAM CALLEE.

The message names the cause exactly. The two builds below answer it: -m makes a module, -c makes an object, and neither of them is an executable.

cobc -m and the module file

-m builds a shared object that the runtime can load when a CALL names it. The name of the file is the name in the CALL, so it is part of the interface:

cobc -m -free -Wall -o CALLEE.so callee.cob
ls -l CALLEE.so

-rwxr-xr-x 1 agent agent 17896 Nov 18 10:33 CALLEE.so

The caller is a main program, so it builds on its own. The call names "CALLEE" in capitals, and the runtime finds CALLEE.so in the folder of the executable:

DATA DIVISION. WORKING-STORAGE SECTION. 01 WS-A PIC 9(5) VALUE 1250. 01 WS-R PIC 9(9) VALUE 0. PROCEDURE DIVISION. CALL "CALLEE" USING WS-A WS-R. DISPLAY "result " WS-R. STOP RUN. END PROGRAM CALLER.

cobc -x -free -Wall -o app caller.cob
./app

result 000003750

The executable is 19744 bytes and holds no copy of the subprogram; the module is a separate file of 17896 bytes and must be beside it at run time. That is the deployment cost of the arrangement, and the reason the run fails when the file is missing:

rm CALLEE.so
./app

libcob: error: module 'CALLEE' not found

The step ends with exit status 1. A job that ships its modules has to ship them with the executable, and a nightly copy that forgets one module shows this line in the log of the first step that needs it.

cobc -c and the link line

-c compiles to an object file and stops there. The link line then puts the object inside the executable, which needs no module at run time:

cobc -c -free -Wall -o callee.o callee.cob
ls -l callee.o
cobc -x -free -Wall -o app2 caller.cob callee.o
./app2

-rw-r--r-- 1 agent agent 7128 Nov 18 10:33 callee.o
result 000003750

The object is 7128 bytes, and the executable with the subprogram inside it is 20928. Two consequences follow from the difference and both matter in a shop with a hundred programs: a change to the subprogram needs a rebuild of every executable that links it, while a module is rebuilt once and every job picks it up at its next run.

The name of the module

A module is found by the exact name in the CALL, and the entry point inside it is the PROGRAM-ID. On a Linux file system those are two different cases, and both have to agree. A call written "callee" looks for callee.so and, when the file is there, does not find the mixed-case symbol:

cobc -m -free -Wall -o callee.so callee.cob
./app3

libcob: warning: loading from existing path './callee.so' failed; Symbol not found: callee
libcob: error: entry point 'callee' not found

With the module named CALLEE.so but the call written , the runtime does not even find a file: it reported module 'CALLEE' not found the other way round, and the two messages together are the whole rule. Write the name in capitals in the CALL, name the module with the same capitals, and the module loads.

A module can also be found through COB_LIBRARY_PATH, which is how a shop keeps one copy of its common modules outside the folder of every job: it is one of the environment variables a job sets before it starts, not a line of its code.

Exercises

  1. Build the module with -O2 as well and compare the size of the file with the one on this page.
  2. Run nm -D CALLEE.so and find the entry point.
  3. Build the subprogram as an object and link two different main programs with it. How many executables hold a copy?
  4. Put the module in a subfolder and run the caller with COB_LIBRARY_PATH set to it.

Questions

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

  1. What does cobc -m build?

    Answer

    A module the runtime can load by the name of the CALL

    The module CALLEE.so was loaded by the caller and the executable held no copy of it.

  2. What does cobc -c build?

    Answer

    An object file for a link line

    The object callee.o went into the link line of app2.

  3. Why does cobc -x refuse the subprogram of the page?

    Answer

    An executable needs a main program, and PROCEDURE DIVISION USING marks a subprogram

    The error line says executable program requested but PROCEDURE/ENTRY has USING clause.

  4. Which file does a call to "CALLEE" need at run time?

    Answer

    CALLEE.so, in the folder of the executable or on COB_LIBRARY_PATH

    The run found CALLEE.so beside the executable and stopped with module not found when it was removed.

  5. What does this program print? IDENTIFICATION DIVISION. PROGRAM-ID. Q5. DATA DIVISION. WORKING-STORAGE SECTION. 01 W-A PIC 9(5) VALUE 1250. 01 W-R PIC 9(9) VALUE 0. PROCEDURE DIVISION. COMPUTE W-R = W-A * 3 DISPLAY W-R. STOP RUN. END PROGRAM Q5.

    Answer

    000003750

    Three times 1250 is 3750 in a nine-digit field.

  6. What does this program print? IDENTIFICATION DIVISION. PROGRAM-ID. Q6. DATA DIVISION. WORKING-STORAGE SECTION. 01 W-A PIC 9(5) VALUE 1250. 01 W-C PIC 9(1) VALUE 0. PROCEDURE DIVISION. CALL "Q6SUB" USING W-A W-C. DISPLAY W-A " " W-C. STOP RUN. IDENTIFICATION DIVISION. PROGRAM-ID. Q6SUB. DATA DIVISION. LINKAGE SECTION. 01 L-A PIC 9(5). 01 L-C PIC 9(1). PROCEDURE DIVISION USING L-A L-C. MOVE 9 TO L-C. GOBACK. END PROGRAM Q6SUB. END PROGRAM Q6.

    Answer

    01250 9

    The callee writes the status into the caller field and leaves the amount alone.

  7. What does this program print? IDENTIFICATION DIVISION. PROGRAM-ID. Q7. DATA DIVISION. WORKING-STORAGE SECTION. 01 W-N PIC 9 VALUE 1. PROCEDURE DIVISION. PERFORM UNTIL W-N IS GREATER THAN 2 DISPLAY "step " W-N ADD 1 TO W-N END-PERFORM. STOP RUN. END PROGRAM Q7.

    Answer

    step 1 then step 2

    The loop runs for the values one and two and stops above two.

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

    Answer

    [CALLEE.so]

    TRIM removes the padding of the sixteen-character field.

  9. A job links its subprograms as objects. What has to be rebuilt when one subprogram changes?

    Answer

    Every executable that links that object

    The object is inside each executable, which is the cost the page names against the module route.

  10. Why does the module route need the file beside the executable?

    Answer

    The call is resolved at run time, by file name

    Removing CALLEE.so made the same executable fail with module not found.

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