| Directives for Compiler | Linking to System Executables | |
The UNIX operating system provides basic functionality to create and execute shared objects. Your COBOL system exploits this and provides additional COBOL-specific functionality via callable shared objects. Your COBOL system also enables you to the create shared libraries. These are a form of shared object used to create system executables. See the chapters Packaging Applications and Linking to System Executables for more details.
Callable shared objects are created with the cob -z
command. See the section Creating Callable Shared
Objects below for details.
Callable shared objects are dynamically loaded at run-time when required. That is, when referenced as a main entry point (for example, by cobrun) or by the COBOL CALL syntax. When all the entry points in a callable shared object have been cancelled then the callable shared object is unloaded, releasing any memory used.
This behavior is similar to .int and .gnt code but differs to linked shared libraries and system executables, which are always loaded at process start-up, whether they are used or not. Further, the code and memory used by shared libraries and system executables are only unloaded when the process terminates.
A callable shared object can contain more than one COBOL program and can also contain other language programs, such as C and C++. Callable shared objects can also be linked with third party object files or shared libraries. This behavior is similar to system executables and shared libraries but differs from .int files and .gnt files, where each file corresponds to a single COBOL program.
Callable shared objects are created with the cob -z
command.
For example:
cob -z myprog.cbl
creates the callable shared object myprog.so. If this is the main (or only) module of an application it can be run using:
cobrun myprog
See the chapter Running
for more details. Alternatively, if myprog is a subprogram, it can
be loaded and run using the COBOL CALL syntax, such as CALL "myprog",
and cancelled and unloaded using CANCEL "myprog".
Several COBOL programs can be combined into a single callable shared object. This has the advantage that any references between the COBOL programs can be resolved using direct references without having to use the dynamic loader to search for and then load another module. For example:
cob -z myprog.cbl subprog.cbl entry.cbl
compiles all the COBOL programs and links them together, creating myprog.so. The main entry point is myprog, the main entry point of the first COBOL program specified, myprog.cbl.
The name of the created callable shared object can be specified with the -o cob flag. For example:
cob -zo entry.so myprog.cbl subprog.cbl entry.cbl
compiles all the COBOL programs and links them together, creating entry.so.
Here, the basename of the callable shared object entry is used as
the main entry point; entry is the main entry point of entry.cbl.
The entry point can also be specified with the -e cob option. This is useful if your application name is not the same as your source program filenames. For example:
cob -zo myapp.so myprog.cbl subprog.cbl entry.cbl -e entry
compiles all the COBOL programs and links them together, creating myapp.so.
The main entry point is specified as entry, which is the
main entry point of entry.cbl. Any entry point in any of the COBOL
programs could be specified with the -e option.
If no -e option is specified then the basename of the callable shared object is used as the main entry point. If the main entry point cannot be found at run-time, the callable shared object cannot be loaded and a run-time load error results.
See the chapter Descriptions of cob Flags for details on the cob -e and -o flags.
For programs compiled with
the LITLINK Compiler directive, calls made using the COBOL syntax CALL
"literal" produce a direct reference to literal.
Any such references are tightly bound to any entry point of the
same name, that is defined in a program specified on the cob line,
when creating a callable shared object. Any direct reference to a name
that does not have a corresponding entry point name, in any program
specified when creating a callable shared object, is called an unresolved
reference.
When a callable shared object is loaded at run-time any unresolved references are resolved by the OS dynamic linker using symbols in the system executable file, loaded shared libraries and any loaded callable shared objects. If any symbol remains unresolved then the callable shared object cannot be loaded and a load error results. On some platforms, one or any of the unresolved symbol names might also be listed.
To prevent a load error all unresolved references must be resolved when the callable shared object is created. This can be done using the -d or -U cob options.
If the name of a unresolved reference is known it can be resolved using the -d option. For example:
cob -z myprog.cbl subprog.cbl entry.cbl -d myref
resolves reference to myref in one of the specified COBOL
programs. When called at run-time myref is dynamically
loaded using the standard search rules that first look at the currently
loaded entry points and then, if myref cannot be found,
search for myref on disk (for example, for myref.so).
To get a list of all unresolved references when you create the callable
shared object, you can use the -z,U cob option. For
example:
cob -z,U myprog.cbl subprog.cbl entry.cbl
creates myprog.so and lists any unresolved references. You can then add -d cob options to resolve the references. You do not need to use -d options for any symbols that you know will be linked into the calling system executable (if not using cobrun or cobrun_t), or which are defined in callable shared objects that you know will have been already loaded.
If you want to resolved all unresolved references then you can use the -U cob option. For example:
cob -z myprog.cbl subprog.cbl entry.cbl -U
creates myprog.so resolving any (and all) unresolved references.
The cob -z option accepts .int files and system object (.o) files as input, as well as recognized source code programs. Hence, C and C++ source and/or object code can be linked into a callable shared object.
For example:
cob -zo myapp.so mycobol.cbl myint.int myc.c myobj.o -e myentry
creates myapp.so using the COBOL programs mycobol.cbl
and myint.int, the C source code myc.c, and an object file
myobj.o. The object file could be COBOL, C, C++ or some other
language or third party system object file. The main entry point is
specified as myentry which could be in any of the specified
modules.
When creating callable shared objects that contain C++, the -z,CC
option should be used so that the C++ compiler creates the final callable
shared object. For example:
cob -z,CC -o myapp.so mycobol.cbl myc.c mycpp.C -e myentry
creates myapp.so using the COBOL program mycobol.cbl,
the C source code myc.c, and a C++ source file mycpp.C.
The main entry point is specified as myentry which could be
in any of the specified modules.
A shared library can be linked into a callable shared library using the -l and -L cob options. The shared library will be loaded when the callable shared object is loaded and unloaded when the callable shared object is unloaded. For example:
cob -Z mylib.cbl myobj.o cob -zo myapp.so myprog.cbl myc.c -L. -lmylib -e myentry
creates a shared library libmylib.so and then links it into myapp.so. When myapp.so is loaded at run-time the OS will search for and load the shared library libmylib.so. See the chapter Linking to System Executables for more details on shared libraries.
A callable shared object does not need to contain COBOL and so could contain just C or C++ or objects supplied by a third party.
In Object COBOL Version 4.1 and earlier products C, C++ or third party objects needed to be linked into a system executable or a new RTS. This is no longer necessary as they can now be linked into callable shared objects. Linking C, C++ or third party objects or shared libraries into a callable shared object allows you greater flexibility when creating applications.
For example, you can now code your application to cope with situations in which a third party product is not installed on a machine. This is achieved by linking the third party objects and shared libraries into a callable shared object, not a system executable. You then load this callable shared object, when required, using the COBOL ON EXCEPTION syntax. If the third party product is not installed then the callable shared object will not load and the ON EXCEPTION route of your code will be taken.
Copyright © 2000 MERANT International Limited. All rights reserved.
This document and the proprietary marks and names
used herein are protected by international law.
| Directives for Compiler | Linking to System Executables | |