Directives for Compiler | COBOL System Interface (cob) |
The Micro Focus COBOL system enables you to execute dynamically linked, statically linked or unlinked programs, all of which can be output by the cob command depending on the options specified to it.
The UNIX system provides basic functionality to build and execute programs. Your COBOL system exploits this and provides additional COBOL-specific functionality. Normally, for simple applications, you do not need to know much detail about how COBOL 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 at the beginning of the section Operation. 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 an executable object file using the system linker to link all the required run time procedure references to an instance of the required code.
A program executable object file, which usually does not have a filename extension, can be run by simply 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. The system's linker and loader supports one or two of the following types of linking and binding :
All UNIX systems support static linking but they do not all support dynamic linking and binding. Dynamic linking involves shared object files (.so files ) that on some systems are known as shared library files (.sl files ) and on others as .a files. Wherever this section refers to an .so file, you can take this to mean an .sl or an .a file if this is what your system uses. If dynamic linking is supported by your system, then it is generally the default type of linking. See your operating system documentation to find out whether and how your system supports dynamic linking and binding.
Dynamic binding of a program or sub-program is carried out by the system loader at run time. The executable file contains a reference to an external procedure (sub-program or even a main program) in a shared object file and the system loader ensures that the procedure is made available for execution. The system loader ensures that, however many concurrent users or applications are dynamically bound to that procedure, they all share a single copy in memory of the dynamically-bound procedure.
Dynamic linking of a procedure is carried out by the system linker at link time. The linker does not include the code for a dynamically linked procedure in the executable file, but does include a reference to the shared object (.so) file that contains the procedure's object code.
Static linking of a program or sub-program is carried out by the linker at link time. The linker includes the object code for all statically linked procedures in the executable object file and resolves all procedure references to them. The linker can be considered to have statically bound these procedures as the system loader does not have to take any special action at run-time.
The Micro Focus COBOL system provides COBOL applications with the standard UNIX functionality for linking and loading as well as a separate COBOL loading facility. Three options are available, for each program and sub-program in a COBOL application, via the cob command that provides:
A dynamically linked program is a subprogram that is held in object form in a shared object or .so file and is referenced from within one or more executable object files.
Dynamic linking is only available if your Operating and COBOL systems support it.
A statically linked program is a program or subprogram that is held in object form in an executable object file. It cannot be referenced from other executable files.
The COBOL Run-time system (RTS) enables you to run a dynamically loadable program without needing to link it first. The run-time system provides a dynamic loader routine that, when linked in an executable object file, can load a dynamically loadable COBOL program or sub-program and execute it.
A dynamically loadable program is either a COBOL intermediate code file or a COBOL generated code file .
Dynamic linking enables .so files to be shared between users and applications and can result in reduced disk space for holding application executable files compared with static linking.
Dynamic linking enables shared objects to be shared between users and applications and can result in reduced memory use for multiple concurrent users of multiple applications at run time compared with static linking.
Static linking lets multiple users share the same application's object code when running and can result in reduced memory use for multiple concurrent users of that one application at run time compared with dynamic loading.
Dynamic loading does not require any linking and can be invoked directly via the cobrun command (see the chapter Running for details). The dynamically loaded files cannot share memory between users at run time, unlike any linked portions of the application. For relatively small applications, relatively numerous applications and relatively small numbers of concurrent users, dynamic loading can result in reduced disk use for holding the applications as well as reduced memory use.
The most significant advantage of dynamic loading over dynamic and static linking is that it removes the need for a link process and so it speeds the compile to run process and gives increased run-time flexibility.
The following sections describe how to build an application, describing the three options available and providing guidance on when you might choose one over the other.
To run a COBOL application, you must first invoke a standard UNIX system executable file. This is loaded by the system loader and control is passed to the first program or entry point. The application starts to run and control passes explicitly to called subroutines or implicitly to run-time support routines.
The default entry point is the start of the first program file specified to
the cob utility when building the application executable file. The first
program, if specified, can be a COBOL program or a non-COBOL program. The
default entry point can be overridden by the -e
flag to cob, to specify an alternative first entry point or to specify that
the name of the first entry point is provided at run time as the first parameter
on the command line that invokes the executable file. See the chapter COBOL
System Interface (cob) for details on the cob command.
An executable file that requires the first entry point to be specified at run time is generally known as an executable run-time system (RTS) . The file $COBDIR/rts32 is the default executable RTS. An executable file that has the first entry point built in at link time is generally known as an executable application.
Any program, sub-program or support routine can be dynamically linked or statically linked in the executable file. Only COBOL programs or sub-programs can be dynamically loaded. If anything implies that dynamic loading might be required, then the dynamic loader support routine is linked in the executable file otherwise it is not. If an executable file is not linked with the dynamic loader, it is referred to as a "fully linked" executable. The dynamic loader can be required if:
data-name
statement is used
-d
is specified to cob. Only the statement CALL literal
with no ON EXCEPTION
clause, when used in a fully linked program, does not imply dynamic loading but
implies direct reference that is vastly superior to dynamic loading in terms of
performance.
Dynamic linking is available only if it is supported by your system. (You can check by seeing if there is no 'B' in the version number on the first line of $COBDIR/cobver) Dynamically linkable code is held in shared object (.so) files . These files are left on disk until required at run time. A shared object is an executable file format produced by the system linker that, unlike a runnable object, lacks an initial entry point. Shared object modules can be used as a library that saves disk space and enables one copy of each sub-program to be shared between several different processes.
If the appropriate shared object library cannot be found at link time, the equivalent archive library (.a) is used instead. In this case, the library is statically linked (see the section Static Linking). The startup code of any executable module that uses dynamic linking is always statically linked.
To execute a dynamically linked program, you enter the program-name and any parameters at the UNIX prompt, having previously set up the dynamic library path. The path is typically set as the value of an environment variable:
See the appendix Micro Focus Environment Variables for details.
Dynamic linking provides a number of advantages over static linking. Because the executable module contains only the name of the shared library rather than its contents, the size of the executable module can be greatly reduced. Similarly, since the linker is not actually linking with the library at link time, the link process is much faster. The memory used by a shared library at run time is shared between one or more concurrent run time systems or applications that use it.
Statically linked code is held in the form of a standard system executable object module that has its code permanently linked in the executable object file. Any required run-time support libraries or object modules are linked in the executable object file, possibly with none, one or more programs and sub-programs for your application.
To execute a statically linked program, you enter the program-name and any parameters at the UNIX prompt.
A statically linked program is more self-contained than a dynamically linked program and can sometimes be more convenient when packaging an application for distribution.
UNIX normally requires the names of all called programs to be provided at link time and requires that all called programs themselves to be provided at link time. The COBOL system removes these requirements for COBOL programs by providing dynamic loading of .int and .gnt files.
The COBOL system lets each call to a program to either be linked directly to the program, if it is available at link time, or to be linked to the dynamic loader. At run time, when the dynamic loader is provided with the program name, it searches for the named program and, if necessary, dynamically loads it.
The program name can be provided to the dynamic loader as either a literal or as the value of a data item. The dynamic loader searches for the named program in the following places:
See the chapter The COBOL Interfacing Environment in your Programmer's Guide to Writing Programs for details on how the file is located.
You can use flags to the cob command to explicitly name the programs that you want to be linked and directly referenced and those that you want to be dynamically loaded. Without explicit instructions, cob takes default actions that depend on how the COBOL source calls the program.
The statement CALL
data-name
enables the name of the called sub-program
to be specified dynamically at run time and implies dynamic loading. In a CALL
statement, an ON EXCEPTION clause specifies the action to take if the
sub-program cannot be loaded. Linked programs are not considered able to give an
exception, unlike dynamically loaded programs and so the ON EXCEPTION clause
implies dynamic loading.
Only the statement CALL literal
with no ON EXCEPTION
clause, when used in a linked program, does not imply dynamic loading.
If a program is invoked in a way that implies dynamic loading, then it is invoked by the run-time system dynamic loader. The dynamic loader first searches the list of loaded programs, sub-programs and support routines before trying to load the program dynamically from disk. If the program is already loaded, by virtue of being linked or previously dynamically loaded without any intervening CANCEL, then the dynamic loader simply passes control to it. If the program is not already loaded, then the dynamic loader searches for a suitable dynamically loadable file. The search order is affected by the environment variable COBPATH and the run-time tunable program_search_order . See the appendix Micro Focus Environment Variables, for details on environment variables, and the the chapter Run-time Configuration for details on trun-time tunables. See also the chapter The COBOL Interfacing Environment in your Programmer's Guide to Writing Programs for details of the search order used for dynamically loadable programs.
There are two types of dynamically loadable program: COBOL intermediate code (.int ) files and COBOL generated code (.gnt ) files. If a program needs to be loaded, then the dynamic loader loads a .gnt file in preference to an .int file for any given program. Although you can reference the name, extension and path of a program file in a CALL statement, we recommend that you omit any path or extension and ensure that the basename of any dynamically loadable file corresponds to the program name.
The COBOL system recognizes various forms of file for a program and assumes all files for a given program have filenames that share the same basename. This basename is taken to be the program name. The COBOL system uses the program name to identify a program and the dynamic loader also uses it to locate a program. Each program has a main entry point identified with the program name.
The main entry point into a program is the default point where execution of the program starts. This is the first non-declarative statement after the Procedure Division header. The COBOL language lets you to specify a program-name in the PROGRAM-ID paragraph. If specified, the program-name represents the name of the main entry point.
The ENTRY statement (see your Language Reference for details) allows additional entry points to be named which represent alternative places for the program to start.
The program is identified by the program name, but once a program is loaded,
by linking or dynamic loading, the names of the entry points become available
for use by the CALL statement. The CANCEL statement must only reference a
program name and when executed causes the program to be unloaded, unless the
program is linked in the executable file. Also see the -l
run-time
switch.
We suggest that, for your convenience, if the PROGRAM-ID paragraph is specified, you make the program-name and the basename of a program source file the same.
Accessing a program via the dynamic loader is much less efficient than accessing it directly via direct reference, even if the program has been statically or dynamically linked. If the program needs to be dynamically loaded, then performance drops still further. However, the dynamic loader does give great build and run time flexibility.
Dynamic loading of programs is especially suitable in a development environment. This is because it requires no link process, speeding the edit, compile and run cycle. It also gives more flexibility; you can even, while debugging, reload a changed version of a sub-program while the rest of the application remains running.
In environments where the application generally runs with a single user, you might need to use dynamically loaded programs if the amount of memory available is limited. Dynamic loading allows you full use of the memory management options provided by the Micro Focus COBOL dynamic loader enabling you to control the amount of memory required by your application.
In environments where the application generally runs with multiple users, both memory efficiency and performance generally favor a fully linked application, unless the sub-programs are very large or very numerous. See the chapter Writing Programs in your Programmer's Guide to Writing Programs for further details on performance.
The following sections summarize the operation of the cob command and explain how to create executable files that are dynamically or statically linked or provide dynamic loading.
The cob processing involved in creating a COBOL executable file is fully described in the chapter COBOL System Interface (cob). This section simply 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 an executable module.
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 convert 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
, +L
and +B
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 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
files if the -x
flag is specified.
The default entry point for the final executable is the base-name of the first input file.
You can create an executable application file simply by specifying the
-x
flag to the cob utility together with a list of the application
files that you want included in the executable file. The application files can
include COBOL or C source files, COBOL .int files or any type of .o
object files. The name of the 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 code and links it with the run-time support routines to produce an executable myprog. The program can then be run by simply entering the name of the 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 code, compiles
the C sourcefile csub.c to an object file, links them together with the
COBOL run-time support routines and creates an executable file myapp.
The -v
flag causes cob to give informational messages on its
progress.
If your application needs to include routines that are held in dynamic (.so) libraries or archive (.a) libraries, then you should read the following sections.
You can create an executable application file that is dynamically linked to
a dynamic library using the -x
flag together with the -B dynamic
or +B dynamic
flags on the cob command line. Full details on
the -x
, -B
and +B
flags are contained
in the chapter Descriptions of cob Flags
. The command line should have the following form:
cob -x filenames [ -B dynamic ]
where filenames
is a list of the files input to the
cob command.
This links all the application programs, sub-programs, COBOL run-time system libraries and operating system support libraries, dynamically where shared libraries are available, otherwise statically. The result is an executable file that, when run, uses the necessary run-time system and other shared libraries .
On environments where dynamic linking is supported, -B dynamic
is the default, so it need not be specified on the command line.
When creating an executable file that is dynamically linked, the code for any referenced modules that are held in shared libraries or shared objects are not included in your executable file. Instead, if such a module is referenced at run time, then the shared object is loaded into memory from the shared object file before control is passed to it.
The cob command uses a shared object (.so) library instead of an archive (.a) library of the same basename. If a cob flag names a library then cob assumes it is a shared object 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 sub-program held in a dynamic library creates a dynamic link to the whole library, whereas a reference to a sub-program held in an archive library only statically links to that sub-program. Unreferenced sub-programs in a dynamic library can be available to the dynamic loader; unreferenced sub-programs in the archive library are not available to the dynamic loader.
The most significant benefits of dynamic linking over static linking apply when many concurrently running, yet different, applications share a significant amount of code. The COBOL run-time support routines represent just such a significant amount of code. For this reason, if dynamic linking is supported by your COBOL system, then the run-time support routines are provided as shared object libraries in $COBDIR/coblib. You do not need to build a shared object library to gain the benefits of dynamic linking.
If you want to build your own shared object libraries, then for non-COBOL programs you normally have to build them using the linker. For information on how to create shared objects or archives, see your operating system documentation.
The COBOL system enables COBOL programs to be included in shared libraries but only in certain environments. See your Release Notes for details on whether and how you can do this for your environment.
You can create an executable application file that is statically linked
using the -x
flag together with the -B
static
or +B static
flags on the cob command line. Full details on the
-x
, -B
and +B
flags are contained in
the chapter Descriptions of cob Flags
. The command line should have the following form:
cob -x filenames [ -B static ]
where filenames
is a list of the files input to the
cob command.
This statically links all the application programs and sub-programs, as well as any required run-time system support routines from the COBOL system archive libraries, to create an executable file that has no dynamic links.
On environments where dynamic linking is not supported, static linking is
the default and you should not specify the -B
flag on the command
line.
When creating a statically linked executable file, any programs that are held in archives are only extracted and linked into your executable module if they are referenced by an object that has already been statically linked into the executable.
The statement CALL
data-name
implies dynamic loading and so does any
CALL statement with an ON EXCEPTION clause. By default, neither case causes any
sub-program to be linked at link time.
Only the CALL literal
statement with no ON EXCEPTION
clause, by default, causes the sub-program named in literal
to be linked at link time. The sub-program named in literal
must conform to any system linker rules for forming names and so cannot be a
filename.
Default actions can generally be overridden by using the appropriate cob
flag. Use the cob flag -d
to specify dynamic loading for a named sub-program so it does not get
linked at link time. Use the
-I
cob flag to link the named sub-program at link time. See
the chapter Descriptions of cob Flags for a list and details of the
available cob flags.
A fully linked executable is one that has no dynamic loading specified or implied. With no dynamic loading required at run time, the dynamic loader support module is not needed and is not included in the executable file. As a result, a fully linked executable file is slightly smaller and executes faster than an equivalent executable that is not fully linked.
If you are linking a large number of routines or large object modules, you should be aware of the following:
ld -r
) command. You
can then link these partially linked modules to the run-time system in the usual
way by specifying the -x
cob flag.
ulimit
to enable linking of large object
modules. This is necessary if your system linker cannot automatically override
the ulimit on your machine. You should set ulimit
to the
size of the largest executable module you expect to produce.
An executable RTS is an executable file that requires the first entry point to be be specified at run-time.
You can use cob to create an executable RTS using the cob command, for example:
cob -xo rts.new
You might also need to specify the -I symb
flag for
any additional support you require for your RTS. For example, you need to
include -I COBWIN2 in the cob command if you want to create a new RTS that
includes windowing support.
You can also create an executable RTS using the mkrts script file (supplied in $COBDIR/src/rts). If you use mkrts, your executable RTS will contain the same level of functionality as the default run-time system ($COBDIR/rts32).
For example, the command:
sh $COBDIR/src/rts/mkrts subprogs.c
creates an executable RTS, called rts32, that is equivalent to the default rts32 but which also includes the C subroutines held in the file subprogs.c.
Any executable that is not fully linked potentially provides dynamic loading. See the section Creating Executables That are Statically Linked earlier in this chapter for a description of a fully linked executable. In most cases, the decision on whether the dynamic loader is required is automatic and depends on the form of the CALL statements used in the program.
The dynamic loader can also be selected by cob flags used to build an executable with:
Specifying the cob option -d
symb
causes
the executable to be built so 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 option -e
""
causes
the executable to be built so the executable file 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 dynamically or statically linked
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 sub-program to be called is a C routine. If
the sub-program is called using the dynamic loader, then if the sub-program is
dynamically or statically linked in the executable file, the linked version is
used and no attempt is made at run time to dynamically load it.
If you do not want a sub-program to be dynamically loaded you can ensure that it is linked in one of two ways:
-I
symb
cob option where
symb
is the name of the sub-program. For example:
cob -x -llib prog.cbl -I rtn1 -I rtn2
literal
with no ON EXCEPTION clause in one
of the programs linked in the executable file. For example, create a dummy COBOL
source file of the following form containing calls to the modules:
procedure division.
call "rtn1".
call "rtn2".
...
call "rtnn
".
then link this dummy file with the remaining modules, as follows:
cob -x -llib prog.cbl dummy.cbl
If the number of routines that you want to link is small, the -I option is ideal; if the number of routines is large, the creation of a dummy COBOL sub-program is a more convenient method.
In the two examples above, the routines rtn1, rtn2, ...,rtnn
are assumed to be included in the library lib
. An archive
library can also be specified directly as an input file, but the routines
still need to be selected for linking in the same way.
You can create a dynamically loadable file as either intermediate (.int ) code or as generated (.gnt ) code files from any COBOL source file. You cannot create a dynamically loadable file for non-COBOL programs. Generated code files are machine code files that are tailored for a particular processor. They run much faster than the equivalent intermediate code file but are not portable between processors.
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 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).
On file systems that support long filenames, filenames for programs that are to be dynamically loadable must be unique in the first 30 characters. This is because filenames longer than the entry point name limit are truncated to that limit when statically linked or dynamically loaded. Therefore, you are recommended to keep program source filenames below 30 characters long. See also the chapter System Limits and Programming Restrictions in your Programmer's Guide to Writing Programs.
Examples
The following example illustrates the use of the -d
cob option
to build an executable file that has the main program prog
statically linked and dynamically loads the sub-programsubprog
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 -u subprog.cbl
At run time, the program prog
can be run by invoking the
executable file:
prog
The dynamic loader loads the sub-program when it is called. If the sub-program 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 an 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 and
statically link in the selection of C subroutines that are held in the file subprogs.c
(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 executable file as myrts. The command line to
build the executable file is:
cob -xe "" subprogs.c -o myrts
At run time, the dynamically loadable program prog
can be run
with the following command line
myrts prog
The following example illustrates how to build an executable file that
contains two programs such that the program to be run is selected at run time.
If neither program calls any sub-routines and the -e
""
option is not used, the executable file is fully linked.
A typical command line to build the executable is:
cob -xe "" prog1.cbl prog2.cbl -o runprog
This creates an executable file runprog that has both programs statically linked in. 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 © 1998 Micro Focus Limited. All rights reserved.
This document and the proprietary marks and names
used herein are protected by international law.
Directives for Compiler | COBOL System Interface (cob) |