Being called from C
The call goes both ways. A COBOL subprogram compiles to an object file with an entry point named after its PROGRAM-ID, and a C program may call that entry point like any other function. The pieces are the object, one initialization call and a link line.
The listings below start at the data division because the checker of this course builds one block as one file: a subprogram with a USING list cannot be built as an executable, and the object it does build needs the C driver beside it. The commands on the page are the real ones.
A COBOL module for C
The file holds two programs. The first is a self-test that calls the second with a known amount; the second is the subprogram the C driver wants. A subprogram with a USAGE list cannot be an executable on its own, so the self-test is the main program of the file and the subprogram is kept by name:
IDENTIFICATION DIVISION.
PROGRAM-ID. TAXSELFTEST.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 WS-AMOUNT PIC S9(9) USAGE COMP-5.
01 WS-RESULT PIC S9(9) USAGE COMP-5.
01 WS-A-OUT PIC Z(8)9.
01 WS-R-OUT PIC Z(8)9.
PROCEDURE DIVISION.
MOVE 200 TO WS-AMOUNT
CALL "TAXCALC" USING WS-AMOUNT WS-RESULT
MOVE WS-AMOUNT TO WS-A-OUT
MOVE WS-RESULT TO WS-R-OUT
DISPLAY "tax " FUNCTION TRIM(WS-R-OUT) " of " FUNCTION TRIM(WS-A-OUT)
STOP RUN.
END PROGRAM TAXSELFTEST.
IDENTIFICATION DIVISION.
PROGRAM-ID. TAXCALC.
DATA DIVISION.
LINKAGE SECTION.
01 L-AMOUNT PIC S9(9) USAGE COMP-5.
01 L-RESULT PIC S9(9) USAGE COMP-5.
PROCEDURE DIVISION USING L-AMOUNT L-RESULT.
COMPUTE L-RESULT = L-AMOUNT * 13 / 100
GOBACK.
END PROGRAM TAXCALC.
The self-test builds with cobc -x and runs without any C at all:
cobc -x -free -Wall -o taxtest callee.cob
./taxtest
echo $?
tax 26 of 200
0
The C driver
The driver includes libcob.h, calls cob_init once and then calls the entry point. The symbol is the PROGRAM-ID in capitals:
#include <stdio.h>
#include <libcob.h>
extern int TAXCALC(void *, void *);
int main(int argc, char **argv) {
int amount = 200;
int result = 0;
cob_init(argc, argv);
TAXCALC(&amount, &result);
printf("tax %d of %d\n", result, amount);
return 0;
}
cobc -c -free -Wall -o callee.o callee.cob
cc -o driver driver.c callee.o -lcob -lm
./driver
tax 26 of 200
Thirteen per cent of 200 is 26, and the number came back through the second pointer. The C side sees two int pointers and the COBOL side sees two COMP-5 fields, which is the same four bytes of the same byte order: the lesson on BY REFERENCE and BY VALUE is the reason COMP-5 is the type that matches a C int and PIC 9(9) is not.
The link line has both libraries. -lcob is the runtime of the COBOL program, and -lm is the maths library that runtime calls; a driver that omits either fails at the link with a list of undefined symbols from libcob.
A record passed by pointer
The same mechanism passes a whole record, and the file has the same shape: a self-test main, then the subprogram that fills the record.
IDENTIFICATION DIVISION.
PROGRAM-ID. FILLSELFTEST.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 WS-CUSTOMER.
05 WS-NAME PIC X(8).
05 WS-AMOUNT PIC S9(9) USAGE COMP-5.
01 WS-A-OUT PIC Z(9)9.
PROCEDURE DIVISION.
CALL "FILLREC" USING WS-CUSTOMER
MOVE WS-AMOUNT TO WS-A-OUT
DISPLAY "[" WS-NAME "] " FUNCTION TRIM(WS-A-OUT)
STOP RUN.
END PROGRAM FILLSELFTEST.
IDENTIFICATION DIVISION.
PROGRAM-ID. FILLREC.
DATA DIVISION.
LINKAGE SECTION.
01 L-REC.
05 L-NAME PIC X(8).
05 L-AMOUNT PIC S9(9) USAGE COMP-5.
PROCEDURE DIVISION USING L-REC.
MOVE "ADA" TO L-NAME
MOVE 1250 TO L-AMOUNT
GOBACK.
END PROGRAM FILLREC.
The C side describes the bytes with a structure of the same shape, and the pointer is the contract:
#include <stdio.h>
#include <libcob.h>
extern int FILLREC(void *);
struct customer {
char name[8];
int amount;
};
int main(int argc, char **argv) {
struct customer c;
cob_init(argc, argv);
FILLREC(&c);
printf("[%.8s] %d\n", c.name, c.amount);
return 0;
}
cobc -x -free -Wall -o filltest fill.cob
./filltest
cobc -c -free -Wall -o fill.o fill.cob
cc -o fdriver fdriver.c fill.o -lcob -lm
./fdriver
[ADA ] 1250
[ADA ] 1250
The name came back as ADA followed by five spaces, because COBOL moved a three-character literal into an eight-character field and padded it, and the structure of the driver is exactly those eight bytes followed by the four of the amount. A C side that reads the name as a string has to know about the padding, which is why a record shared like this gets a version field and a note in the copybook.
cob_init
cob_init starts the COBOL runtime: it allocates the working storage of the modules, sets the locale and prepares the file handling. A driver that calls a COBOL entry point without it is stopped at once:
#include <stdio.h>
#include <libcob.h>
extern int TAXCALC(void *, void *);
int main(void) {
int amount = 200;
int result = 0;
TAXCALC(&amount, &result);
printf("tax %d of %d\n", result, amount);
return 0;
}
cc -o noinit noinit.c callee.o -lcob -lm
./noinit
echo $?
libcob: error: cob_init() has not been called
1
One message and exit status 1, from the runtime and not from the COBOL program. The two calls that belong beside it are cob_resolve, which looks a module up by name and answers its entry pointer, and the plain external declaration that the driver of this page uses, which is the same thing decided at link time.
The next lesson builds the same call as a module loaded at run time, which is how a C program keeps its COBOL out of its own executable.
Exercises
- Add a rate parameter to TAXCALC and pass it from the driver.
- Change the name field of the record program to PIC X(10) and adjust the C structure. What happens to the amount if you do not?
- Remove -lm from the link line and read the message of the linker.
- Call the entry point twice and print both results.
Questions
A new set of questions in a new order every time. Choose one answer for each, then check.
-
What is the entry point of a COBOL subprogram in the object file?
Answer
Its PROGRAM-ID, in capitals
The driver declared TAXCALC and the link found it.
-
Which call starts the COBOL runtime from C?
Answer
cob_init(argc, argv)
Without it the driver stopped with cob_init() has not been called.
-
Which C type matches a COBOL PIC S9(9) USAGE COMP-5?
Answer
int
The driver passed int pointers and the COBOL side read COMP-5 fields.
-
Which libraries does the link line need?
Answer
-lcob and -lm
The build of the page links both.
-
What does this program print?
IDENTIFICATION DIVISION. PROGRAM-ID. Q5. DATA DIVISION. WORKING-STORAGE SECTION. 01 W-A PIC S9(9) USAGE COMP-5 VALUE 200. 01 W-R PIC S9(9) USAGE COMP-5. PROCEDURE DIVISION. COMPUTE W-R = W-A * 13 / 100 DISPLAY W-R. STOP RUN.Answer
+0000000026
Thirteen per cent of 200 is 26, and a COMP-5 field displays ten digits.
-
What does this program print?
IDENTIFICATION DIVISION. PROGRAM-ID. Q6. DATA DIVISION. WORKING-STORAGE SECTION. 01 W-NAME PIC X(8). PROCEDURE DIVISION. MOVE "ADA" TO W-NAME. DISPLAY "[" W-NAME "]". STOP RUN.Answer
[ADA ]
The literal is padded to the eight characters of the field, which is what the C structure saw.
-
What does this program print?
IDENTIFICATION DIVISION. PROGRAM-ID. Q7. DATA DIVISION. WORKING-STORAGE SECTION. 01 W-A PIC S9(4) USAGE COMP-5 VALUE 12. 01 W-B PIC S9(4) USAGE COMP-5 VALUE 30. 01 W-T PIC S9(9) USAGE COMP-5. PROCEDURE DIVISION. ADD W-A TO W-B GIVING W-T DISPLAY W-T. STOP RUN.Answer
+0000000042
Twelve and thirty add to forty-two, which goes into the wider field.
-
What does this program print?
IDENTIFICATION DIVISION. PROGRAM-ID. Q8. DATA DIVISION. WORKING-STORAGE SECTION. 01 W-A PIC 9(3) VALUE 200. 01 W-B PIC 9(3) VALUE 13. 01 W-R PIC 9(5). PROCEDURE DIVISION. COMPUTE W-R = W-A * W-B / 100 DISPLAY W-R. STOP RUN.Answer
00026
The arithmetic of the display field gives the same twenty-six as the COMP-5 one.
-
Why must the C structure match the COBOL record byte for byte?
Answer
The pointer is the whole contract: the callee writes its layout where the caller reserved bytes
The name of eight bytes and the int that followed it were written by the COBOL program.
-
What does cob_resolve answer?
Answer
The entry pointer of a module it finds by name
It is the run-time form of the external declaration the driver of the page uses.
The code on this page was built with cobc (GnuCOBOL) 3.2.0 and gcc 15.2.0 on Alpine Linux 3.24.3 (x86_64) in a Docker container.
Article author: Arthur Isaev