Interoperability with C, Java and Python

Whether CALL "literal" is resolved when the program is linked or when it runs is a compile-time choice. By default cobc generates a run-time lookup, so a CALL can reach a program in another file that is loaded on demand (Subprograms CALL and Linkage). With -fstatic-call (the same as -static) it generates a direct C call that the linker resolves. The generated C shows the difference (cobc -C writes it out):

Both builds above worked because the C file was given to cobc on the command line and became part of the executable. When it is not, the two kinds of call fail differently, and the messages are real:

The static form finds a missing function before the program ever runs; the manual lists that all called programs are verified to be present, and a slightly faster call, as the benefits of static linking. The dynamic form is the one that allows a C file built separately as a module. cobc -m -Wall circ_c.c produced circ_c.so, and the same executable ran with COB_LIBRARY_PATH=. only when the module had been loaded first:

The run-time search finds a module by the file name of the shared object, which here is circ_c.so and not the name of any function inside it. That is the reason for the manual’s remark that the binary must be named like the CALL target or have been loaded before; COB_PRE_LOAD loads it up front. A C module that contains several functions should therefore be preloaded, or linked into the executable, instead of being found by function name.

Source: GnuCOBOL 3.2 manual: Dynamic linking with C programs; Optimize call

BY VALUE is a COBOL 2002 phrase meant for exactly this: the argument is a number placed on the call stack or in a register, not an address. GnuCOBOL 3.2 changed one detail that matters whenever both sides are compiled by different versions. The release notes list it under "Changes that potentially effect recompilation of existing programs": in 64-bit environments, a BY VALUE parameter without an explicit SIZE IS clause used to be passed as a 32-bit value and is now passed as a 64-bit value; to pass 32 bits, write SIZE IS 4, and to keep relying on the default, caller and callee must both be compiled with a version before 3.2, or both since. The following program shows what each C parameter type receives. The values are chosen to expose sign and width.

Compiled with cobc -x -Wall sizes.cob sizes.c, no warnings, it prints:

The generated C shows how: every integer BY VALUE argument is widened (with its sign) to a 64-bit cob_u64_t before the call, and a floating-point one is passed as a double. On the 64-bit calling conventions used on Linux, a C function that declares short or int reads the low bits of the register and gets the right value, so the widening is harmless to C. It matters when the callee is itself a GnuCOBOL program compiled with PROCEDURE DIVISION USING BY VALUE, because the two sides must agree on the width, and it matters on a calling convention where arguments are laid out on the stack by size. To ask for a 32-bit argument explicitly, put SIZE IS 4 before the item (the phrase is written ahead of the identifier):

Compiled with cobc -x -Wall size4.cob sizes.c, no warnings, it prints int -70000, and the generated call now passes a cob_u32_t to a function declared void (*)(cob_u32_t). RETURNING NOTHING tells cobc that the C function is void, so no result is expected (another 3.2 addition for calling C directly, along with CALL-CONVENTION and ENTRY-CONVENTION).

Source: GnuCOBOL 3.2 manual: CALL; the GnuCOBOL 3.2 NEWS file, section "Changes that potentially effect recompilation of existing programs", in the source distribution at ftp.gnu.org/gnu/gnucobol

BY VALUE is for numbers. Naming an alphanumeric item there is a mistake that cobc -Wall catches, because C cannot receive a COBOL string by value:

cobc silently changes the call into BY CONTENT, which passes the address of a temporary copy, and the C function status_text(char code) then received that address as if it were the character. The program printed status W is Unknown, a wrong answer with only a warning to show for it. The correct form passes the item by reference to a function that takes a pointer, and takes the returned const char * into a USAGE POINTER, then overlays a LINKAGE item on it with SET ADDRESS OF (the technique of Pointers and Dynamic Storage):

Compiled with cobc -x -Wall -I. callc2.cob circ_c.c (and with -std=ibm), no warnings, it prints:

STRING ... DELIMITED BY LOW-VALUE copies up to the NUL byte that ends the C string, which also keeps the program from using the 40 bytes of LK-TEXT beyond the end of the literal. The address belongs to C: the COBOL program must not FREE it, and the C function must return storage that outlives the call (a literal, a static buffer, or memory the C side agrees to release later).

Source: GnuCOBOL 3.2 manual: Static linking with C programs

A COBOL program compiled for static use is an ordinary C function whose name is the PROGRAM-ID and whose parameters are the USING items, each a pointer. The manual shows the prototype extern int say(char *hello, char *world) for a module with two PIC X parameters; here it is for FINECALC:

Built with cobc -c -Wall finecalc.cob -o finecalc.o and gcc -std=c11 -Wall -Wextra -pedantic direct.c finecalc.o -lcob, it prints:

Built again with -DSKIP_INIT, so that cob_init is not called, the same program fails at its first COBOL statement with the run time’s own message and exit status 1:

That check is why cob_init comes first in every C program above. A caller that wants to choose a module by name at run time, and to report a missing one instead of stopping, uses cob_resolve, which returns a function pointer or NULL, together with cob_resolve_error for the text:

Compiled with gcc -Wall -Wextra resolve.c -lcob (the conversion of the object pointer returned by cob_resolve to a function pointer is what -pedantic objects to, as in the manual’s own example), it prints days=12 fine=004.20 rc=0 when FINECALC.so is on COB_LIBRARY_PATH, and cannot load FINECALC: module 'FINECALC' not found (exit status 1) when it is not. cob_tidy shuts the COBOL run time down but lets the C program carry on, while cob_stop_run ends the process; the manual points out that errors inside COBOL end the program like STOP RUN does, and describes cob_call_with_exception_check for callers that must regain control.

Source: GnuCOBOL 3.2 manual: Static linking with COBOL programs; Dynamic linking with COBOL programs

There are two ways to declare a C function so that COBOL can call it, and two for the other direction. The form without a pragma needs no special declaration: the arguments travel as C passes them, so COBOL names them BY VALUE.

The second form marks the C function with #pragma linkage(name,COBOL), which makes it use the COBOL convention, so the arguments arrive by reference, as they do between COBOL programs:

In the other direction, a C program that calls the COBOL program FINECALC declares void FINECALC(int) and passes the value when the COBOL program says PROCEDURE DIVISION USING BY VALUE LK-DAYS, or declares #pragma linkage(FINECALC,COBOL) and passes the address when the COBOL program uses plain USING LK-DAYS. The pairs above are the patterns of the interlanguage guide, written with Circulation names.

Source: z/OS 3.2 Language Environment Writing ILC Applications (PDF): Communicating between C and COBOL

The guide gives tables of which combinations work. The ones that matter in practice:

The guide also covers data-type equivalents (a one-byte char against PIC X, short against PIC S9(4) BINARY, int against PIC S9(9) BINARY, and so on), strings, condition handling when an exception occurs in COBOL (including CEEMRCR) and output ordering when COBOL is the main routine and C writes to the same stream. Under CICS, the Programming Guide says that ILC with other high-level languages is supported, refers to the ILC guide for the rules, and names CICS LINK, XCTL and RETURN as the alternative where ILC is not supported.

DLLs are a third route between C and COBOL. The Programming Guide states that COBOL DLL support interoperates with the DLL support of the z/OS C/C products, except for COBOL `EXTERNAL` data: COBOL can call functions exported from C/C DLLs, and C/C++ can call COBOL programs that a COBOL DLL exports. A C function can also return a function pointer that COBOL keeps in a FUNCTION-POINTER item (CALL "c-function" RETURNING fp, then CALL fp), the case discussed with the pointer features on Pointers and Dynamic Storage.

Source: z/OS 3.2 Language Environment Writing ILC Applications (PDF); Enterprise COBOL for z/OS 6.5 Programming Guide (PDF): Using subprograms; Creating a DLL or a DLL application

The directive is written >>JAVA-CALLABLE anywhere before the PROCEDURE DIVISION header of the outermost program of the compilation unit. The program must have a well-defined interface of Java-compatible parameters and an optional RETURNING item, and its name is at most eight characters long, because the stub calls it dynamically. The Circulation fine rule becomes:

The four build steps are those of Programming Guide chapter 18 (compile, build the stub DLL, link, compile the Java). The commands below follow the guide’s cob2 and cjbuild forms; the directory and library names are placeholders:

USERID.CIRC.LOAD must be in the STEPLIB when the program runs, because the generated stub finds FINECALC by a dynamic call, and the Java program finds the DLL through java.library.path (for a DLL on the z/OS UNIX file system) or the STEPLIB (for a data set). The stub’s Java signature is generated from the COBOL definition, so the Java compiler checks the argument types at compile time. The class is called progs in the package named by the -p option of cjbuild (enterprise.COBOL when the option is omitted), and the name of the method is the upper-cased program name, unless the program name is written as a literal or compiled with PGMNAME(LONGMIXED), in which case the case is kept exactly.

Source: Enterprise COBOL for z/OS 6.5 Programming Guide (PDF): Making an existing program callable from Java; Compiling, linking, and running non-OO COBOL applications that interoperate with Java; Language Reference (PDF): COBOL/Java interoperability, JAVA-CALLABLE

The compiler decides how to convert each parameter from its definition. The Java-compatible elementary types are these (the Language Reference gives the full tables, including the array types):

Three rules follow from it. A parameter that corresponds to a primitive type, a String or a BigDecimal is read-only to COBOL (a change is not seen by the Java caller), whatever the passing mode; a single-dimension array of a primitive type is shared, so COBOL updates are visible to Java; and a fixed OCCURS table must have exactly as many elements as the Java array it receives (no OCCURS DEPENDING ON), or a java.lang.IllegalArgumentException is thrown. A group that does not fit an array pattern is a plain byte array, and the Java code must lay the bytes out as the COBOL group defines them; the compiler warns with message IGYPA3415I when it makes that assumption. Packed and zoned numbers become BigDecimal by conversion routines of IBM’s JZOS toolkit, and the guide warns that passing large arrays of BigDecimal or String is expensive. On the COBOL side, COMP-1 and COMP-2 in the table above are IBM hexadecimal floating point by default, converted to and from IEEE for Java.

Source: Enterprise COBOL for z/OS 6.5 Language Reference (PDF): Mapping between COBOL and Java data types for non-OO COBOL/Java interoperability; Programming Guide (PDF): Using Java-compatible array types in COBOL

A COBOL program that writes an audit line through a Java logging class uses an ordinary CALL with a literal target. The class name is qualified with its package, the nested classes are introduced by a dollar sign, the Java. prefix is not case-sensitive and the rest is. Arguments convert by the same table.

Only static methods can be called. Every exception during the call, on the Java side or in the generated call stub, is handled by ON EXCEPTION: the exception is cleared before the phrase runs, and the Java exception object is available through the special register IGY-JAVAIOP-CALL-EXCEPTION, from which the JNI function Throw() can propagate it. Without ON EXCEPTION an exception stops the run unit. In the other direction, an exception inside the stub’s JNI calls goes straight back to Java for the Java code to catch. A static Java method can also catch its own exceptions and return a code, which the COBOL program tests like any RETURNING result.

JAVA-SHAREABLE ON and JAVA-SHAREABLE OFF bracket 01 and 77 level items of the WORKING-STORAGE SECTION that Java may read and write through the generated strg class (strg.PROGRAM.ITEM.get() and .put(...), with an index for a table element). The program has to have been called at least once, so that its storage is initialized; shared names must be unique across the COBOL part of the application and at most 26 characters long, because the mechanism uses EXTERNAL items; and a shareable item of a type that is not Java-compatible is ignored.

Source: Enterprise COBOL for z/OS 6.5 Programming Guide (PDF): Calling static Java methods from COBOL; Accessing COBOL WORKING-STORAGE data items from Java; Handling errors in Java-interoperable COBOL applications; Language Reference (PDF): JAVA-SHAREABLE

The JAVAIOP compiler option has these suboptions (it can be given only for the first program of a batch compilation):

cjbuild runs from the z/OS UNIX shell or from JCL through BPXBATCH, and writes the DLL to a z/OS UNIX directory or to a data set. Its options in the 6.5 Programming Guide are:

The last argument is the library base name, from which the DLL is named lib<name> on the UNIX file system and, in the 6.5 documentation, <NAME> for a data set. The guide states that before Enterprise COBOL 6.5 the LIB prefix was also added to the member name of a data set, so a build job that links against the side deck must drop the prefix when it is moved to 6.5. The program file (the list of programs) became an optional argument, so that all stub files in the directory are processed by default.

The three AMODE combinations of chapter 48 and their build flags are:

For the mixed combination at run time, the guide sets LIBPATH to the Java library directories and exports IBM_JAVA_OPTIONS="-XX:+Enable3164Interoperability". The OO framework is not supported with AMODE 64 Java, which is one more reason to prefer the non-OO route for new work. Language-wise, AMODE 64 COBOL is described on Pointers and Dynamic Storage (POINTER-32 and LP(64)).

Java 25 or later asks for one more setting: the guide says to specify the JVM option --enable-native-access=ALL-UNNAMED to avoid warnings that JNI is a restricted function, through COBJVMINITOPTIONS for an application that starts in COBOL (or the JVMINITOPTIONS suboption), and in the usual Java configuration for one that starts in Java. Support for running with Semeru Java 25 arrived as a 6.5 PTF (PH70635, March 2026, per IBM’s What’s new page), and the other service-stream changes of 6.5 are summarized on Compilers and Dialects.

Source: Enterprise COBOL for z/OS 6.5 Programming Guide (PDF): JAVAIOP; cjbuild command reference; AMODE considerations; IBM, What’s new in Enterprise COBOL for z/OS 6.5

The Java side of this chain, compiling, packaging and the module system, is on the Java reference: Build and Tooling (Java) and Exceptions (Java); BigDecimal against COBOL decimal arithmetic is on Numbers and Math (Java).