|Callable Shared Objects||COBOL System Interface (Cob)|
This chapter describes how to link programs to create system executables.
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:
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.
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.
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.
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
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
(ld), passing program files and options to it in the same order
+L flags; see the chapter
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
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.
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:
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
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.
You can create a system executable application file that is linked to a
shared library file or includes an archive file using the
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:
List of the files input to the cob command.
||Changes the order in which the system linker searches for libraries that were specified with the -l cob flag.|
||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
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.
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
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:
Specifying the cob option
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.
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.
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
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
-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:
literalwith no ON EXCEPTION clause in one of the programs linked into the system executable file.
cob -x prog.cbl -I subprog -l lib
Alternatively, the archive library can be turned into a shared library using the -Z cob flag.
If you use COBOL syntax of the form
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.
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
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.
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:
You can create .gnt files by using the
-u flag, as
cob -u filenames
filenames is a list of the COBOL files input
to the cob command.
You can create callable shared objects by using the
flag, as follows:
cob -z filenames
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).
The following example illustrates the use of the
option to build a system executable file that has the main program prog
linked and dynamically loads the subprogram
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:
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
specifies that the entry point, or the main program is given at run time
-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:
and in order to run the second program, enter the command line:
Copyright © 2000 MERANT International Limited. All rights reserved.
This document and the proprietary marks and names used herein are protected by international law.
|Callable Shared Objects||COBOL System Interface (Cob)|