The following information pertains to UNIX/Linux platforms, for commands entered on the command line (i.e. at a shell prompt), or commands within makefiles or build scripts.

If you are already familiar with the "cob" command and its flags (including the "-x" flag), you might briefly review the following introduction, then skip to the section below named "Problem".

Introduction

To create a system executable, use the "cob" command with the "-x" flag.  For example:

 cob -x myprog.cbl

 ./myprog

In this example, "cob -x" invokes the COBOL compiler to compile "myprog.cbl" to object code (creating "myprog.o"), then automatically invokes the system linker "ld" behind the scenes to link "myprog.o" with COBOL runtime libraries to produce a system executable named "myprog".  The executable can then be invoked by its name at the command line.

If an application contains several programs, all the programs can be linked together. Consider this example:

cob -x myprog.cbl mysub.int csub.c -o myapp

This compiles "myprog.cbl" and "mysub.int" to object code, then invokes the C compiler to compile the C program "csub.c" to object code, then invokes the system linker "ld" behind the scenes to link them together with COBOL libraries to create an executable named "myapp".  This is one way C modules might be linked together with COBOL modules into an executable .

System shared libraries can participate in a "cob -x" link.  Shared libraries have names with the prefix "lib" and the extension ".so" (or ".sl" on HP-UX PA-RISC).  Shared libraries can include several COBOL modules and/or C modules. To make shared libraries participate in the link, the syntax is:

cob -x filenames [-L dir] [-l name]

where:

"filenames" is a list of the files input to the cob command,

"-L dir" changes the order in which the system linker searches for libraries specified with the -l cob flag, and

"-l name" means that libname.so (or libname.a) will be searched to resolve any references during the link

For example:

cob -x prog.cbl -L/home/lib/mylibs -labc

This brings the shared library /home/lib/mylibs/libabc.so into the link.

The "cob" command can create shared libraries with the "-Z" flag, .  Example:

cob -Z myprog.cbl

This compiles the program "myprog.cbl" then invokes the system linker "ld" to create a shared library named "libmyprog.so".

A shared library can include a combination of COBOL or C source files, .int files, or any type of .o file.  Example:

cob -Z myprog.cbl mysub.int csub.c -o libmyapp.so

This compiles the COBOL programs "myprog.cbl" and "mysub.int" to .o files, compiles the C source file "mysub.c" to .o, then links them all together to create the shared library "libmyapp.so".

For more information about "cob -x" and creating system executables, consult the Server Express documentation in the area of Bookshelf > User's Guide > Part 2 "Creating Applications" > Chapter 8 "Linking to System Executables",

or the Visual COBOL and Enterprise Developer documentation in the area of General Reference > Command line reference > Compiling and Linking from the Command Line (UNIX) > Creating Different Types of Files

Problem:

Application developers sometimes try to create system executables that include COBOL modules, by using a method other than "cob -x", for example by using the "cc" command or "ld" command.  This may appear to work at first, but this can cause crashes or error messages when the application is run.

Solution:

The only supported method of creating system executables that include COBOL modules, is to use "cob -x".  Executables that include COBOL modules, but that were created in some other way, such as by using "cc" or "ld", are not supported by Micro Focus.  The runtime behavior of such executables is considered "undefined". 

Here are some reasons application developers might try to use "cc" or "ld", and not "cob -x", to create executables:

(1) The developers might hope to create stand-alone executables with the necessary COBOL runtime libraries already linked in, that could potentially be executed on machines on which MF COBOL has not been installed, or could potentially run outside the MF COBOL licensing system.  But this idea will not work; it is not possible to successfully run executables that include COBOL modules, without the MF COBOL product (or at least the MF COBOL runtime product i.e. "Server for COBOL") installed and licensed on the machine.

(2) The developers might be mostly C developers, accustomed to creating executables with the "cc" command.  They might imagine that:

 -- Since the COBOL compiler can produce .o (object) files from COBOL source code, or can produce shared libraries with "cob -Z", and

 -- since the COBOL runtime system perhaps consists of just a few libraries from $COBDIR/lib (such as libcobrts.so, libcobcrtn.so, and libcobmisc.so),

 -- therefore it should be possible to create executables this way:

cob -c cobprog1.cbl        <-- creates cobprog1.o

cc mainprog.c cobprog1.o -L$COBDIR/lib -lcobrts -lcobcrtn -lcobmisc

or this way (using a shared library):

cob -Z cobprog1.cbl       <-- creates libcobprog1.so

cc mainprog.c -L. -lcobprog1 -L$COBDIR/lib -lcobrts -lcobcrtn -lcobmisc

They might hope this would allow them to use "cc" as they are accustomed (though executables created this way are actually unsupported).

The "cc" command allows developers to pass options to the C compiler and to the linker.  Particular C compiler options and linker options might be mandatory for the success of the application (especially if the application includes a lot of C code).  So the developers might wonder, since Micro Focus prohibits creating executables with "cc" or "ld", how can the necessary options be passed to the C compiler or the system linker?

The answer is that "cob -x" can do nearly everything "cc" or "ld" can do.  If you give "cob -x" a C program, or an object (.o), or a library, or a COBOL program, then "cob -x" will know what to do with it.  If you have an option you'd like to pass to "cc", you can specify this using the "-CC" flag of the "cob" command.  To pass options to the system linker, use the "-Q" flag of the "cob" command.  For complete information about the flags the "cob" command accepts, consult the Server Express documentation, User's Guide, Chapter 10 "Descriptions of cob Flags", or the Visual COBOL and Enterprise Developer documentation in General Reference > Command line reference > Compiling and Linking from the Command Line > cob Flags.

For every "cc" option or "ld" option there is an equivalent "cob" flag, thus a "cc" or "ld" command line previously used to create executables can be translated into an equivalent "cob -x" command line.

The "-vD" flag tells the "cob -x" command to reveal the "cc" and "ld" commands it invokes behind the scenes.  If you specify "cob -x -vD", the "cob" command will echo the complete "ld" command lines it uses to perform the link.  You can see the COBOL libraries that "cob" has decided to include, and the linker options "cob" has decided to specify for its own purposes, in addition to any linker options you have told "cob" to pass to the linker using the "-Q" flag.

The reason Micro Focus requires executables to be created using "cob -x" is that the "cob -x" command reserves the right to specify which libraries in $COBDIR/lib should be linked in (i.e. which libraries correctly constitute the COBOL runtime system), and which options should be passed to the linker for the purposes of the COBOL runtime system.  If end-users create executables with their own "cc" or "ld" commands, Micro Focus cannot be certain that the correct COBOL libraries will be specified, or that the correct linker options will be specified.  These libraries and linker options may change from version to version of MF COBOL, and may be different and unique on each UNIX/Linux platform.  But the "cob -x" command supplied with a particular version and platform can be trusted to specify the correct options.

There have been historical cases where end-users created executables using "cc" or "ld" instead of "cob -x", then ran the executables successfully without error for months or years, and encountered errors only when upgrading to a new version of MF COBOL.  The end-users saw this as a regression in the COBOL product's behavior, and demanded that the new COBOL version be fixed to work like the old version.  Micro Focus' reply in such cases is that the practice was never supported, that the behavior has always been regarded as "undefined", that it was merely fortunate it once worked with a particular version of MF COBOL, and that the solution to the errors is to begin creating executables using the supported method of "cob -x".

If an end-user is experiencing crashes or error messages at runtime, but they have created executables using "cc" or "ld" instead of "cob -x", Micro Focus' first requirement will be that they begin using "cob -x" instead.  Micro Focus will perform additional analysis only if the crashes or error messages continue to occur after the executables are created using "cob -x".