Calling C from COBOL
A CALL does not care what language the callee is written in. The C library is already linked into every executable the compiler produces, so printf, toupper and strlen are available to a COBOL program without a single line of C to write.
CALL "printf"
A C function takes its arguments by value and its strings as a pointer to the first character. COBOL says the same thing with BY VALUE for the number and by reference, the default, for the format:
IDENTIFICATION DIVISION.
PROGRAM-ID. C1.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 WS-FMT PIC X(20) VALUE "value %d" & X"00".
01 WS-NUM PIC S9(9) USAGE COMP-5 VALUE 42.
PROCEDURE DIVISION.
CALL "printf" USING BY REFERENCE WS-FMT BY VALUE WS-NUM.
DISPLAY " ".
STOP RUN.
cobc -x -free -Wall -o c1 c1.cob
./c1
echo $?
value 42
8
Two things happened there that a COBOL program does not expect. The line came out, and the exit status of the program is 8: C functions return a value in the same register that becomes RETURN-CODE, and printf returned the eight characters it printed. The program ends with STOP RUN, so the shell sees the count of characters as the status of the job.
The fix is the line the next programs have: MOVE 0 TO RETURN-CODE before STOP RUN, or a RETURNING clause that takes the value into a field of the program instead of leaving it in the register.
Numbers BY VALUE
A C int is four bytes of binary in the byte order of the machine, and the COBOL field that matches it is PIC S9(9) USAGE COMP-5. The pair below is the smallest useful C call:
IDENTIFICATION DIVISION.
PROGRAM-ID. C2.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 WS-CH PIC S9(9) USAGE COMP-5 VALUE 97.
01 WS-UP PIC S9(9) USAGE COMP-5.
01 WS-LEN PIC S9(9) USAGE COMP-5.
01 WS-TEXT PIC X(20) VALUE "hello" & X"00".
PROCEDURE DIVISION.
CALL "toupper" USING BY VALUE WS-CH RETURNING WS-UP.
DISPLAY "toupper " WS-UP.
CALL "strlen" USING BY REFERENCE WS-TEXT RETURNING WS-LEN.
DISPLAY "strlen " WS-LEN.
MOVE 0 TO RETURN-CODE.
STOP RUN.
cobc -x -free -Wall -o c2 c2.cob
./c2
toupper +0000000065
strlen +0000000005
97 is the code of a and toupper answered 65, the code of A. strlen read five characters and stopped, because the field ends with the zero byte that & X"00" put there.
RETURNING works for a C callee, which is the one place in this course where the clause is useful: the page on RETURNING and RETURN-CODE showed why it does not work for a COBOL one.
Strings by reference
A COBOL field is a fixed width and a C string ends at a zero byte, so the field that travels to C carries the byte itself. A format with a string and a number shows both directions at once:
IDENTIFICATION DIVISION.
PROGRAM-ID. C3.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 WS-FMT PIC X(40) VALUE "name=%-6s qty=%3d" & X"00".
01 WS-NAME PIC X(6) VALUE "apple" & X"00".
01 WS-QTY PIC S9(4) USAGE COMP-5 VALUE 12.
01 WS-COUNT PIC S9(9) USAGE COMP-5.
PROCEDURE DIVISION.
CALL "printf" USING BY REFERENCE WS-FMT
BY REFERENCE WS-NAME
BY VALUE WS-QTY
RETURNING WS-COUNT.
DISPLAY " ".
DISPLAY "printf returned " WS-COUNT.
MOVE 0 TO RETURN-CODE.
STOP RUN.
cobc -x -free -Wall -o c3 c3.cob
./c3
name=apple qty= 12
printf returned +0000000019
The name was printed as apple and not as apple with the six characters of the field, because %s stops at the zero byte. The count of 19 is the length of the line the format produced, and it went into WS-COUNT through RETURNING, so the exit status of the run stays 0.
The next lesson turns the call around: a C program that calls a COBOL subprogram. The two directions use the same rules and the same field types, and the page after it puts the whole thing in one build.
Exercises
- Call "toupper" on the code of a lowercase letter read from a field, once for a letter and once for a digit.
- Remove the X"00" from the name of the third program and read the line it prints.
- Print the value of RETURN-CODE after the first program and explain the 8.
- Call "abs" with a negative COMP-5 number and a RETURNING field.
Questions
A new set of questions in a new order every time. Choose one answer for each, then check.
-
Which COBOL field matches a C int?
Answer
PIC S9(9) USAGE COMP-5
The page passes and receives C ints in COMP-5 fields.
-
What does a C function need for an alphanumeric argument?
Answer
The address of the field, with a zero byte at the end of the string
The name field ended with X"00" and strlen read five characters.
-
Why did the first program exit with status 8?
Answer
printf returned the eight characters it printed and that value stayed in RETURN-CODE
The run printed value 42, which is eight characters.
-
Where does a C return value go with CALL ... RETURNING?
Answer
Into the field named by RETURNING
The count of printf went into WS-COUNT and the exit status stayed 0.
-
What does this program print?
IDENTIFICATION DIVISION. PROGRAM-ID. Q5. DATA DIVISION. WORKING-STORAGE SECTION. 01 W-N PIC S9(9) USAGE COMP-5 VALUE 97. 01 W-R PIC S9(9) USAGE COMP-5. PROCEDURE DIVISION. CALL "toupper" USING BY VALUE W-N RETURNING W-R. DISPLAY W-R. MOVE 0 TO RETURN-CODE. STOP RUN.Answer
+0000000065
The uppercase of a lowercase letter has the code 65.
-
What does this program print?
IDENTIFICATION DIVISION. PROGRAM-ID. Q6. DATA DIVISION. WORKING-STORAGE SECTION. 01 W-T PIC X(10) VALUE "abc" & X"00". 01 W-L PIC S9(9) USAGE COMP-5. PROCEDURE DIVISION. CALL "strlen" USING BY REFERENCE W-T RETURNING W-L. DISPLAY W-L. MOVE 0 TO RETURN-CODE. STOP RUN.Answer
+000000003
The string ends at the zero byte after the three letters.
-
What does this program print?
IDENTIFICATION DIVISION. PROGRAM-ID. Q7. DATA DIVISION. WORKING-STORAGE SECTION. 01 W-F PIC X(10) VALUE "n=%d" & X"00". 01 W-N PIC S9(9) USAGE COMP-5 VALUE 7. 01 W-C PIC S9(9) USAGE COMP-5. PROCEDURE DIVISION. CALL "printf" USING BY REFERENCE W-F BY VALUE W-N RETURNING W-C. DISPLAY " ". DISPLAY "count " W-C. MOVE 0 TO RETURN-CODE. STOP RUN.Answer
n=7 on one line and count +0000000003 on the next
The line n=7 is three characters and the count follows it; a COMP-5 field displays ten digits.
-
What does this program print?
IDENTIFICATION DIVISION. PROGRAM-ID. Q8. 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. PROCEDURE DIVISION. CALL "abs" USING BY VALUE W-A RETURNING W-B. DISPLAY W-B. MOVE 0 TO RETURN-CODE. STOP RUN.Answer
+012
The absolute value of minus twelve is twelve in a signed four-digit field.
-
Why is MOVE 0 TO RETURN-CODE needed after a C call?
Answer
The return value of the C function lands in the register that becomes the exit status
The first program of the page exited with the count printf returned.
-
Which two languages does a COBOL program need for a printf call?
Answer
None: the C library is linked into every executable the compiler makes
The three programs of the page are one file each and call C directly.
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