PreviousCallable Shared Objects COBOL System Interface (Cob)Next

Chapter 9: Linking to System Executables

This chapter describes how to link programs to create system executables.

9.1 Introduction

Server Express enables you to execute linked system executable programs or dynamically loaded programs (.int files, .gnt files and callable shared objects), which can be output by the Cob utility depending on the options specified to it.

The UNIX system provides basic functionality to build and execute programs. Server Express exploits this and provides additional COBOL-specific functionality. Normally, for simple applications, you do not need to know much detail about how Server Express builds and executes programs as the Cob utility provides generally useful defaults. In this case, you can skip this section and simply read the initial discussions on the cob command and default linking in the section Simple, Default Linking. However, if you want to optimize the way UNIX handles your built application or if you want to include non-COBOL routines in your application, then you need to understand more of the functionality available and how the COBOL system uses it. In this case, you should read this section.

This section describes:

For information on using the Cob utility, see the chapter COBOL System Interface (Cob). If you are working in 64-bit mode, you should also see the chapter Working in 32-bit and 64-bit Modes.

9.1.1 UNIX System Linker and Loader

Programming language compilers generally output a program as an individual, unlinked object (.o) file. This type of file is incomplete and cannot be directly executed. It lacks the various system or language support routines and possibly called subroutines that are needed at run time. It can be used to build a system executable file or shared library file using the system linker to link all the required run-time procedure references to an instance of the required code.

A system executable file, which usually does not have a filename extension, can be run by entering the name of the file at the UNIX system prompt. UNIX invokes the system loader to load the program file together with any linked procedures and to bind all procedure references to a loaded copy of the procedure.

9.1.1.1 Linking and Binding

A shared library file has a prefix of lib and filename extension of .so (or .sl on HP/UX). A shared library can be linked into one or more system executables. When the system executables are executed the system loader loads one copy of the shared library, shares the code area and creates separate data areas for each executable. The shared library remains loaded until the system executable process terminates.

Shared libraries should not be confused with callable shared objects, which also have the filename extension .so. Callable shared objects are a callable file format, which means that they are dynamically loaded and unloaded at run-time, if and when required. Shared libraries can be linked into callable shared objects. See the chapter Callable Shared Objects for more information.

Binding of a program or subprogram is carried out by the system loader at run time. If the executable file contains a reference to an external procedure (subprogram or even a main program) in a shared library file, the system loader ensures that the procedure is made available for execution. The system loader ensures that, however many concurrent users or applications are bound to that procedure, they all share a single copy in memory of the dynamically-bound procedure.

Linking of a procedure is carried out by the system linker at link time. The linker does not include the code for a linked procedure in the system executable file, but does include a reference to the shared library file that contains the procedure's object code.

9.1.2 Linking

Dynamically linkable code is held in shared library files. These files are left on disk until required at run time. A shared library file is an executable file format produced by the system linker that, unlike a runnable system executable file, lacks an initial entry point. A shared library saves disk space and enables one copy of each subprogram to be shared between several different processes.

If the appropriate shared library file cannot be found at link time, the equivalent archive library (.a) is searched for instead. In this case, the library is said to be statically linked.

Statically linked code is created from standard object (.o) files (that can be grouped together into archive files) that has its code permanently linked into a system executable file by the system linker. Static linking enables multiple users to share the same application's object code when running. But, unlike shared libraries, the object code cannot be shared between different applications.

The start-up code of any system executable is always statically linked. The COBOL run-time system is always dynamically linked.

To execute a linked program, you enter the program-name and any parameters at the UNIX prompt, having previously set up the library path. The path is typically set as the value of an environment variable:

See the appendix Micro Focus Environment Variables for details.

9.2 Linking Using the cob Command

The cob processing involved in creating a COBOL system executable file is fully described in the chapter COBOL System Interface (cob). This section highlights and summarizes the most significant aspects of using cob for linking.

The cob processing for a source file, named myfile.cbl, that is input to the cob command with the -x flag specified, can be shown as:

myfile.cbl-> myfile.int-> myfile.o->myfile

where the final myfile is a system executable file. See the chapter Creating Programs for more information.

The cob command assumes that all files and options specified on the command line are required if the -x flag is included. The cob command recognizes many files by their filename extension and recognizes many flags and options. It acts upon recognized flags and converts recognized files to their end point. It then invokes the system linker (ld), passing program files and options to it in the same order (except the +l and +L flags; see the chapter Descriptions of cob Flags) that they were specified on the cob command line. The system linker then carries out the required type of linking to create the final system executable file.

Take care when specifying files and flags to cob, as it passes them on to the linker unchanged if it does not recognize them. It cannot check unrecognized ones itself and so cannot flag any error. You should not specify .gnt or callable shared objects if the -x flag is specified.

The default entry point for the final system executable file is the basename of the first input file, specified on the cob command line. The first program can be a COBOL or non-COBOL program. You can override the default entry point with an alternative using the cob -e flag.

9.2.1 Simple Default Linking

You can create a system executable application file by specifying the -x flag to the cob command, together with a list of the application files that you want included in the system executable file. The application files can include COBOL, C or C++ source files, .int files or any type of .o object files. The name of the system executable file is the basename of the first application file in the list unless you specify another name by using the -o flag. For example, the command line:

cob -x myprog.cbl

compiles the program myprog.cbl to native object code and links it with the run-time support routines to produce a system executable myprog. The program can then be run by entering the name of the system executable at the command line. If the current directory is not set in your PATH environment variable, you can run the program with a command line:

./myprog

If your application contains several programs, then all the programs can be linked together. For example, the command line:

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

converts myprog.cbl and mysub.int to native object code, compiles the C source file csub.c to an object file, links them together with the COBOL run-time support routines and creates a system executable file myapp. The -v flag causes cob to give informational messages on its progress.

If your application contains code written in C++ then the -x,CC cob flag should be used so that the C++ compiler (and not the system linker) creates the final system executable. For example, the command line:

cob -x,CC myprog.cbl mysub.int csub.c cppsub.C -o myapp

creates the system executable myapp using the COBOL programs myprog.cbl and mysub.int, the C source file csub.c and the C++ source file cppsub.c.

The default initial entry point of a system executable application file is the basename of the first program name on the command line, such as myprog in the previous example. If your application requires a different initial entry point, use the cob -e flag. For example:

cob -xo myapp myprog.cbl subprog.o -e myentry

specifies myentry as the initial entry point.

If your application needs to include routines that are held in shared libraries or archive (.a) libraries, then you should read the following sections.

9.2.2 Creating Executables That Use Library Files

You can create a system executable application file that is linked to a shared library file or includes an archive file using the -l flag on the cob -x command line. Full details on the -l flag are contained in the chapter Descriptions of cob Flags . The command line should have the following form:

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

where the parameters are:

filenames

List of the files input to the cob command.

-L path Changes the order in which the system linker searches for libraries that were specified with the -l cob flag.
-l name libname.so (or libname.a) is to be searched to resolve any references

This links all the application programs and subprograms with the specified libraries as well as the default COBOL run-time system libraries and operating system support libraries. The result is a system executable file that, when run, preloads the specified shared libraries before execution is passed to the main entry point.

When creating a system executable file, the code for any referenced modules that are held in shared libraries are not included in your system executable file. Instead, if such a module is referenced at run time, then the shared library is loaded into memory from the shared library file before control is passed to it.

The cob command uses a shared library in preference to an archive library of the same basename. If a cob flag names a library then cob assumes it is a shared library, but if no such library exists then it uses an archive library of the same name.

For example, if you specify two libraries abc and xyz on the cob command line as follows:

cob -x prog.cbl -labc -lxyz

where the libraries libxyz.so, libxyz.a and libabc.a exist, then only libxyz.so and libabc.a are scanned to resolve references and libxyz.a is ignored.

Bear in mind that a reference to a subprogram held in a shared library file creates a link to the whole library, whereas a reference to a subprogram held in an archive library only links to that subprogram. Unreferenced subprograms in a shared library file can be available to the dynamic loader; unreferenced subprograms in the archive library are not available to the dynamic loader.

9.2.3 Creating Shared Libraries

Shared libraries are created with the cob -Z command.

As shared libraries cannot be directly executed, they need to be linked into a system executable or callable shared object. Hence, shared libraries are searched for by the system linker during the link process. This means that a shared library name must always start with the prefix lib and have the extension .so (or .sl on HP/UX).

Unless the cob -o flag is specified, cob creates a shared library name of libname.so (or libname.sl on HP/UX), where name is the basename of the first application supplied to cob. For example:

cob -Z myprog.cbl

compiles the program myprog.cbl to native object code and then links it to create a shared library libmyprog.so.

A shared library can be created from a combination of COBOL, C and C++ source files, .int files or any type of .o files. For example:

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

compiles the COBOL programs myprog.cbl and mysub.int to native object code, compiles the C source file mysub.c to an object file and then links them together to create the shared library libmyapp.so.

If any C++ code is linked into a shared library, the cob -Z,CC flag should be used so that the C++ compiler (and not the system linker) creates the shared library file. For example:

cob -Z,CC myprog.cbl mysub.int csub.c cppsub.C

creates the shared library libmyprog.so using the COBOL programs myprog.cbl and mysub.int, the C source file csub.c, and the C++ source file cppsub.C

9.2.4 Creating an Executable RTS

An executable RTS is a system executable file that requires the first entry point to be specified at run-time. In Object COBOL V4.1 and earlier, an executable RTS was required when you needed to link C and C++ programs into your application. However, C and C++ programs can now exist within callable shared objects; therefore it is no longer necessary to create an executable RTS for this. See the chapter Callable Shared Objects for more details.

If you require, you can create an executable RTS using cob. For example:

cob -xo rts.new subprogs.c -e ""

creates an executable RTS that contains the same level of functionality as the default run-time system ($COBDIR/bin/rts32 or $COBDIR/bin/rts32_t) that also includes the C subroutines held in the file subprogs.c. At run-time the dynamically loadable program myapp could then be run with the command line:

./rts.new myapp

Specifying the cob option -e "" causes the system executable to be built so that the executable file's entry point must be specified at run time.

Full details of the cob -e flag can be found in the chapter Descriptions of cob Flags.

9.2.5 Dynamic Loading

UNIX normally requires both the names of all called programs, and the called programs themselves, to be provided at link time. The COBOL system removes these requirements for COBOL programs by providing dynamic loading of callable shared objects, .int files and .gnt files.

The COBOL system enables each call to a program to be either linked directly to the program, if it is available at link time, or to be linked to the dynamic loader. At run time the dynamic loader searches for the named program and, if necessary, dynamically loads it.

For more detailed information on dynamic loading, see the section Dynamic Loading in the chapter Packaging Applications.

9.2.5.1 Creating Executables That Use the Dynamic Loader

The dynamic loader enables callable file formats to be loaded dynamically at run-time. See the chapter Packaging Applications for more details.

In Object COBOL V4.1 and earlier the dynamic loader was automatically linked into a system executable depending on the form of the CALL statements used in the program. In Server Express, the dynamic loader is always included.

The dynamic loader can also be selected by cob flags used to build a system executable with:

Specifying the cob option -d symb causes the system executable to be built so that if the program named symb is called at run time, it is loaded dynamically; cob gives an error if the program is presented to cob for static linking.

Specifying the cob -e"" flag causes the system executable to be built so that the executable file's entry point must be specified at run time. You specify the entry point at run time by including the name of the entry point on the command line. The dynamic loader is used to locate the named program, first checking if the program is linked or previously loaded and, if not, trying to load the program dynamically.

Full details on the -d and -e flags are contained in the chapter Descriptions of cob Flags.

The statement CALL data-name and any CALL statement that includes an ON EXCEPTION clause implies use of the dynamic loader. However, you might not want dynamic loading, for example if the subprogram to be called is a C routine. If the sub-program is called using the dynamic loader, then if the sub-program is linked into the system executable file, the linked version is used and no attempt is made at run time to dynamically load it.

If you have a subprogram in an archive library and you do not want the subprogram to be dynamically loaded you can ensure that it is linked by using one of the following:

Alternatively, the archive library can be turned into a shared library using the -Z cob flag.

9.2.5.2 Resolving Unresolved References

If you use COBOL syntax of the form CALL "literal" a direct reference is produced to literal.

If you create a system executable, any such references are tightly bound only if an entry point literal is provided when the program is linked. If no entry point literal is available, the reference to literal is unresolved and a link error is produced.

Unresolved references can be resolved by using cob -d symb. This causes the system executable to be built in a way that enables symb to be dynamically loaded at run-time.

For example:

cob -x myprog.cbl subprog.cbl -d myref

resolves the reference to myref in one of the specified COBOL programs. When myref is called at run-time the dynamic loader is invoked to search for and load the call to myref.

If there are several unresolved references you can resolve them all at once using the cob -U option. For example:

cob -x myprog.cbl subprog.cbl -U

creates myprog, resolving any (and all) unresolved references.

9.2.5.3 Creating Dynamically Loadable Files

A dynamically loadable file can be created as an .int file, .gnt file or callable shared object from any COBOL source file. For more details see the chapters Compiling Programs and Callable Shared Objects.

The cob command creates .int files by default, for example:

cob filenames

You can create .gnt files by using the -u flag, as follows:

cob -u filenames

where filenames is a list of the COBOL files input to the cob command.

You can create callable shared objects by using the -z flag, as follows:

cob -z filenames

where filenames is a list of the COBOL files input to the cob command.

To run dynamically loadable files, they must be called by an executable RTS or application. A convenient way is to use the cobrun command (see the chapter Running for details).

Examples:

The following example illustrates the use of the -d cob option to build a system executable file that has the main program prog linked and dynamically loads the subprogram subprog at run time:

cob -x prog.cbl -d subprog

A typical command line for creating a dynamically loadable file for subprog as high performance machine code is:

cob -z subprog.cbl

At run time, the program prog can be run by invoking the system executable file:

prog

The dynamic loader loads the subprogram when it is called. If the subprogram cannot be found and loaded, then if an ON EXCEPTION clause for the CALL exists it is executed, otherwise the run-time system gives an error.


Note: To run a system executable file by just giving its filename on the command line, the file must be held in a directory that appears in your PATH environment variable. Alternatively you can specify the full pathname, which for the above example would be . /prog .


The following example illustrates how to build an executable RTS that contains two programs such that the program to be run is selected at run time (see the section Creating an Executable RTS for further details). The cob option -e "" specifies that the entry point, or the main program is given at run time and the -o option specifies the name of the system executable file as runprog.

cob -xe "" prog1.cbl prog2.cbl -o runprog

This creates a system executable file runprog that has both programs linked into it. To run the first program, enter the command line:

runprog prog1

and in order to run the second program, enter the command line:

runprog prog2




Copyright © 2000 MERANT International Limited. All rights reserved.
This document and the proprietary marks and names used herein are protected by international law.

PreviousCallable Shared Objects COBOL System Interface (Cob)Next