COBOL System Interface (cob) | Descriptions of cob Error Messages |
This chapter describes the flags that can be used with the cob command to specify any action the system components should take to determine the type of file output. As noted in the chapter COBOL System Interface (cob), the type of module output (for example, .int, .gnt and .o as well as executable modules) depends upon the type of file input and the options specified to the cob command. cob output files by default are placed in the source directory; if you want to put executable files created using cob in another directory, you can specify the -o flag (see the description later in this chapter).
The descriptions of flags appear alphabetically, with upper-case flags listed before lower-case flags. Each entry shows the function, flag and setting and any options required.
Passes the specified option to the UNIX system assembler (as).
Compiles the COBOL source files (with extension .cbl, .CBL or .cob) input to the cob command into an intermediate code file (with the extension .int) and Animator files (with extension .idy), both of which are used by Animator (see the chapter Animator, in your Object COBOL Character Tools for details on using Animator.)
Any object module files (with extension .o), C source files, or assembler source files input to the cob command are linked with the COBOL libraries to form a single executable file, which also can be used by Animator. This enables you to animate programs that call, or are called by, programs that are written in languages other than COBOL.
The -a flag does not specify an end point for cob processing, only the type of intermediate code file produced by the COBOL Compiler.
Because this is the default action for the cob command, you do not actually have to specify the -a flag on the cob command line. However, you might find it useful to do so for clarity in your coding.
For example, if you use the command:
cob -a myfile.cbl c.o
The files myfile.int, myfile.idy and c are created. The file c contains the run-time system and the file c.o. The command:
cob myfile.cbl c.o
has the same effect. To animate myfile.int, use the commands:
COBSW=+A export COBSW c myfile.int
Selects the file binding mode used by the system linker and passes the -Bmode
option to the linker command line. Valid options are static
for
production of a fully statically linked executable, and dynamic
for production of an executable which uses dynamic linking. The default is
dynamic
.
Note: The -B flag is supported only on UNIX operating systems that support dynamic linking. If your operating system does support it (that is, the library libcobol.so exists in $COBDIR/coblib), see your operating system manual for more details on static and dynamic linking.
-B mode
is added to the linker command line before the
COBOL libraries. Any user-defined libraries specified with the -l flag inherit
the current binding mode. If more than one -B flag is used, the binding mode for
any subsequent user-defined libraries are set, but the user-defined libraries
already defined are unaffected. The last -B flag sets the binding mode for the
COBOL libraries.
If the binding mode is dynamic
, then the shared object (.so)
version of the library, if it exists, it is used. Otherwise, the archive (.a)
version of the library is used. If the binding mode is static
,
then the choice of archive (.a) is forced, even if a shared object (.so)
version also exists.
For example, entering the following on the cob command line:
cob -x prog.cbl -B static -lxyz -B dynamic
specifies that the .a version of libxyz is to be used, but all other libraries (for example, the COBOL library libcobol, or the operating system library libc) are to use the .so version (where available).
Using the optional syntax =lib
sets mode
for the specified library only, where lib
is any library
that appears on the linker line, whether it is from the command line or a COBOL
library defined in the file $COBDIR/coblib/liblist or as specified in the
environment variable LIBLIST. If mode
is dynamic
and no .so version of the library specified exists, then the .a
version (if one exists) is used.
When specifying libraries in this way, you should be aware of the following:
lib
is specified with both binding modes, then the
last mode defined on the command line is used. For example, entering the following on the cob command line:
cob -x prog.cbl -B dynamic -B static=screen
specifies that all the libraries are to be dynamic, except the COBOL library libscreen, which is to be statically linked. Thus, the shared object (.so) versions of libraries are chosen over corresponding archive (.a) versions, except library libscreen, where the archive version is chosen even if there is a shared object version.
Has the same effect as -B except that relative ordering is not preserved. +B
mode
is converted to -B mode
and is
passed to the system linker after the COBOL libraries and before the system
libraries (specified in liblist).
Note: The +B flag is supported only on UNIX operating systems that support dynamic linking. If your operating system does support it (that is, the library libcobol.so exists in $COBDIR/coblib), see your operating system manual for more details on static and dynamic linking.
Because -B mode
is added to the linker command line
after the COBOL libraries and before the system libraries, it defines the
binding mode of only the system libraries and any user-defined libraries
specified with the +l flag.
Using the optional syntax =lib
sets mode
for the specified library only. For example, entering the following cob command
line:
cob -x prog.cbl -lxyz -B static +B dynamic +labc +B static
creates a statically linked RTS with the user-specified libraries
dynamically linked. Note that the default mode, -B dynamic
, is
implied before the -lxyz
. Hence, the .so version of libxyz
and libabc (if they exist) are used, while the .a versions of the COBOL
and system libraries are forced by the -Bstatic
and +Bstatic
flags respectively.
The same result also could be produced by entering the cob command line:
cob -x prog.cbl -lxyz -B static +labc +B dynamic=abc
Note that -B dynamic
is again implied before -lxyz
.
This flag is only supported on SCO OpenServer Release 5, and specifies the object module format of any object produced, regardless of the source language (that is, COBOL, C, or assembler). This option behaves exactly the same as the cc -b option.
format can have the value:
ibcs2 is an alias for coff. The values for format can take any case.
Passes directive
to the Compiler's syntax-check phase, where directive
is one or more of the Compiler directives listed in the chapter Directives
for Compiler.
Passes cc_option
to the C compiler
via cc. If you specify the -CC cob flag, you must ensure that the only
options you enter are options used by the C compiler itself. This is because the
system assumes that if you are using the cob command rather than cc to compile a
C program, you want to link the C program to COBOL programs before it is run. To
do this, cob needs the .o file output by the C compiler once it has
compiled the C program. cob can then take the resulting .o file and link
it with other object modules to create a COBOL executable file. Therefore, you
should not try to use the -CC flag to pass options that the Compiler normally
would try to pass to the system linker.
Suppresses the link editing of any static linked executable, so the object modules can subsequently be statically linked. This option does not specify an end point and has an effect only if the specified end point would cause link editing; for example, if the -x cob flag had been specified.
Causes the symbol symb
to be dynamically loaded if it
is called. symb
is any valid COBOL name. This option can
be used when producing a static or dynamic linked executable file, to specify
any missing modules that are to be loaded dynamically at run time. Thus, you can
use this flag to allow certain run-time support modules to be loaded as
necessary rather than to be permanently loaded. For example, if in your program
there are Adis operations, the Adis module by default is linked to your program.
If, however, you want
Adis to be dynamically loaded, you should specify the symbol ADIS behind the
-d flag on the cob command line (for details on the Adis module, see the chapter
Adis).
Overrides the default entry point symbol, using instead the symbol
identified by epsym
, which must already have been defined
in a COBOL module. By default, the entry point address for a statically or
dynamically linked module is the base-name of the first file input to the cob
command. If you want the entry point address to be read from the command line at
run-time, you can define the value of epsym
as null, that
is -e "".
Allows the fast creation of a statically or dynamically linked executable module with dynamic load support by making all the entry points and external data (from both COBOL and C modules) available to dynamically loaded programs. This is achieved by cob creating an entry for each entry point and all external data in a loaded table (ldtab), when it produces a statically linked executable module.
Entries are created in ldtab only for modules named on the command line and in a default list found in $COBDIR/coblib/cobfsym. Any symbols for objects in archive (.a) or shared object (.so) files are not included in ldtab, thus reducing the time taken to create a statically linked executable module. If a reference from a dynamically loaded module is made to any name that is not in ldtab (even if it is included in the linked executable), then you receive RTS error 173:
Called program file not found in drive/directory
See the +F flag for details of how to add symbols to ldtab.
Note that you cannot specify this flag if you set the -U flag.
Provides the same behavior as the -F flag, except that the default list is
taken from fname
rather than from$COBDIR/coblib/cobfsym.
There must be no spaces in -F,fname
.
Enables the fast creation of a statically or dynamically linked executable
module with dynamic load support, as with the -F flag, and adds the specified
symbol to the loaded table (ldtab).
Once symb
has been added to ldtab, any call to a
module of that name causes control to be passed to the function identified by
symb
. At link time, the error "undefined symbol(s)"
occurs if symb
is not part of the static linked executable
being produced.
You cannot specify this flag if you set the -U flag.
Generates the files input to the cob command into a .gnt file and Animator information files (with the file extension .gdy), both of which are used by Animator (see the chapter Animator in your Object COBOL Character Tools).
Creates additional information needed for the use of a symbolic debugger such as sdb. With this flag set, no symbols are stripped from the output file. This flag is passed through to the C compiler if any .c files are being processed, so it is useful if your program contains some C functions that you want to debug. It also passes the ANIM directive to the Compiler .
Marks symb
for inclusion in the executable output
file. When symb
is pulled in by the system linker, the
entire object, as well as any other objects that are referenced, is pulled in.
For example, you need to include -I COBWIN2 in the cob command if you want to
create a new RTS that includes windowing support.
The -I flag is particularly useful with a static RTS, as certain modules not referenced by default can be included if required. This flag is not necessary with dynamic linking as anything referenced at run time is included automatically.
The following list shows the symbols that are automatically included in a build of a new RTS:
Symbol |
Module |
---|---|
ANIM | Animator |
COBCOMMS | ANSI communications support |
DYNLOAD | Dynamic loader |
INTERPRET | COBOL interpreter for .int code |
PROFILE | COBOL Profiler |
SORT | Sort module |
USERCALL | Usercall support |
The following list shows the symbols that are not automatically included in a build of a new RTS but can be included using the -I flag. Some are only applicable if you are using a relevant add-on product.
Symbol |
Module |
---|---|
CCINAMPU | CCI modules for named pipe support |
CCITCP | CCI modules for TCP support |
CICS | Pointer conversion utilities for OS/VS COBOL |
COBWIN2 | Windowing support |
DSRTNS | Dialog System RTS support |
FHREDIR | Fhredir file handling redirector |
fhutil | File handler |
OOPS | OO RTS support |
SESSION | Session handling |
Note: You can create an executable RTS using the mkrts script. mkrts includes in an executable RTS all of the functionality of rts32 (the default run-time system). See Creating a Run-time Executable in the chapter Linking for deatils.
Compiles the COBOL source code (.cbl, .CBL or .cob) files input to the cob command into dynamically loadable intermediate code files (with the file extension .int). These files can then be run without any further processing.
Identifies to cob COBOL source files either with no extensions or with extensions other than the default extensions .cbl, .CBL or .cob. This allows COBOL files without the recognized extension to be compiled without having to alter their filename.
Changes the order in which the system linker searches for libraries that were specified with the -l cob flag. -L options affect only those -l options that they precede on the cob command line.
The -L cob flag is effectively the same as the -L option for the system linker, ld (see your operating system documentation for further details on this linker option). By default, the directories /lib (or /usr/ccs/lib) and /usr/lib are searched first for these libraries. However, specifying the -L flag causes the system linker instead to search the specified directory first for such libraries. The order in which -L options are specified is significant as directories are searched in that order.
On systems that support dynamic linking, paths in the environment variable LD_LIBRARY_PATH, or LIBPATH (on AIX systems) or SHLIB_PATH (on HP/UX systems) are searched before -L, +L and the default paths.
Example
The following example illustrates the use of the +L and -L flags in determining the order in which directories are searched for libraries:
cob +L /usr/mylib +llib1 object.o -L /usr/grouplib -llib2 +llib3
The relative ordering of the options passed to the system linker (assuming the complete search path for every library needed to be searched) would be:
Note that LD_LIBRARY_PATH in the above example might be LIBPATH or SHLIB_PATH, depending on your UNIX system.
The complete search path for every library would be searched only if a status of "file not Found" is returned on earlier paths.
Has the same effect as -L except that relative ordering is not preserved. +L options are passed (as -L options) to the system linker after all other objects and linker options. The ordering of +L and +l options relative to each other is preserved. See the description of -L for an example of the search order.
Causes the system linker to search the specified library for any external
routines. For statically linked executables created using the -B static flag,
lib
takes the form liblib
.a. For
dynamically linked executables created using -B dynamic, it takes the form liblib
.so.
The -l cob flag is effectively the same as the -l option for the system linker,
ld (see your operating system documentation for further details on this linker
option). The order in which -l options are specified is significant as
directories are searched in that order.
If you specify the -l flag with the -B static flag, the .a version of the library is searched for and loaded into the executable at link time. If you specify the -l flag with the -B dynamic flag, the .so version of the library is searched for and, if found, is used at run time. If no .so version exists, the .a version is then searched for and loaded. Thus, if you specifically want the archive library rather than a shared object library, you should use the -B static flag.
A library is searched when its name is encountered, so the placement of the -l flag is significant. By default, libraries are located in the directories /lib (or /usr/ccs/lib) and /usr/lib. However, you can use the -L flag to specify an alternative search path.
Example
The following example illustrates the use of the +l and -l flags in determining the order in which libraries are searched for symbols:
cob -llib1 +llib2 obj1.o -llib3 obj2.o
The relative ordering of the options passed to the system linker would be:
The system linker accepts options delimited with a hyphen (-), so once the relative ordering has been determined, the +l flag options are converted to -l before being passed to the linker.
Has the same effect as -l lib
except that relative
ordering is not preserved. +l options are passed (as -l options) to the system
linker after all other options and files. Thus libraries specified with +l are
searched after the COBOL libraries. The ordering of the +L and +l options
relative to each other is preserved. See the description of -L for an example of
the search order.
Maps unresolved symbol symb
to newsym
,
which must already have been defined in a COBOL module. This creates a stub
routine to satisfy any references to symb
, so if this new
routine is called, control is passed to the routine that has the entry name
newsym
. This flag enables you to "dummy out"
unwritten optimized routines into one general purpose routine, if the calling
sequence is the same. For example:
cob -x -m s1=x1 -m s2=x2 myprog.cbl mylib.a
maps the unwritten routines s1() and s2() to the functionally similar x1() and x2() routines, which must already have been coded.
You also can use this flag to map parts of static or dynamic linked executables produced by cob onto user-supplied routines or tailored modules. Possible RTS symbols that can be mapped are:
Symbol |
Description |
---|---|
sqfile | sequential fixed length record file handler |
ixfile | indexed fixed length record file handler |
rlfile | relative fixed length record file handler |
lsfilev | line sequential variable length record file handler |
sqfilev | sequential variable length record file handler |
ixfilev | indexed variable length record file handler |
rlfilev | relative variable length record file handler |
When mapping symbols from any of the COBOL libraries, such as the file
handler symbols above, if newsym
has unresolved references
to a user library, use the +L and +l flags to specify the library search path
and name to ensure references from the COBOL libraries to the new symbols are
correctly located.
If you do use this option to substitute the file handler supplied by Micro Focus with your own file handler, your file handler must conform to the Micro Focus Callable File Handler interface standard (see the chapter Callable File Handler in your Programmer's Guide to File Handling for details). Additionally, you can use the -m flag to link with the RTS a version of C-ISAM other than the version supplied with your Micro Focus COBOL system.
Passes the specified option
to the Compiler's generate phase. directive
is one or
more of the generate phase directives listed in the chapter Directives for
Compiler.
Enables maximum performance at run time by carrying out the minimum run-time checks. This option is for use after all debugging has taken place and maximum performance with minimum run-time checks is required. The exact operation of this flag is environment dependent, but at a minimum it passes the NOCHECK directive to the Compiler. If any .c files are being processed, this flag also is passed through to cc.
Changes the default name of the static linked executable module created using the -x option to the filename specified. The default filename is the basename of the first file entered to the cob command.
Produces a listing file (with the extension .lst) for each COBOL source file input to the cob command. Any errors detected by the Compiler are also reported both on standard error and in the listing file (at the point at which the error was located).
Passes the option -p to the C compiler. If linking to produce a statically or dynamically linked executable module, it causes cob to use profiling startup and termination routines that call monitor (3) and causes the monitor information to be written to the file mon.out on normal termination of the executable module. See your system manual for more details on the -p flag.
Some operating systems do not support profiling for dynamically linkable executables, so if profiling is required, the executable should be compiled using the -B static flag.
Passes the specified cob option(s) to the system linker. The Micro Focus
COBOL system uses a two-pass link process to build a static or dynamic
executable to support dynamic loading and reference to C external data.
Specifying -Q ld_option
passes the options to both linker
passes (that is, calls of the command ld). Specifying -Q,1 ld_option
passes the options to only the first linker pass. Specifying -Q,2 ld_option
passes the options to only the second linker pass.
The -Q,2 ld_option
flag cannot be used with the -F and
+F flags.
You must use a separate -Q flag for each option, and any options that begin
with hyphens must be enclosed in quotation marks. Use the format -Q "flag
value
" only where flag
and value
are not separate arguments, but represent one argument containing an embedded
space.
Causes any unresolved reference to be treated as a COBOL program to be dynamically loaded. Normally, such references would cause a fatal error at link time.
This option cannot be used with the -F and +F flags.
Compiles the COBOL source code files (.cbl, .CBL or .cob) into intermediate code and then generates them to dynamically loadable native code (generated code) files. These files have the file extension .gnt.
You can supply intermediate code files to the cob command instead of COBOL source code files; these are just code generated. You can also input any object module files (.o) to the cob command; these are statically linked to the dynamic loader to produce the static run-time library for dynamically loadable files. Dynamically loaded programs can call any of the modules in the statically linked run-time library as well as any other valid dynamically loadable program.
Examples
The following examples illustrate the types of processing available using the -u flag:
cob Command line |
Output Files |
---|---|
cob -u tmp/a.cbl |
a.int, a.gnt |
cob -u b.cbl |
b.int, b.gnt |
cob -u a.int |
a.gnt |
cob -u tmp/b.int |
b.gnt |
Sends to the screen the version number of any of the COBOL system components that have been invoked. This option is passed to the system programming utilities (for example, cc and ld).
Sends to the screen messages output by the Compiler concerning accepted directives, the size of the code and data areas, and the entry points of each module. This flag also outputs to the screen warning messages concerning non-error conditions (for example if a flag you have specified overrides one you have already set), which by default are suppressed. Additionally, it echoes to the screen the entire command line when it is passed to cob.
Causes cob processing to terminate after the COBOL Compiler err-level
has been exceeded. By default, the cob command terminates
if your code contains reported errors in the category severe or above.
err-level
is a single alphabetic character
representing the possible levels of error:
Character |
Level |
---|---|
u | unrecoverable |
s | severe |
e | error |
w | warning |
i | information |
The cob process (not the compile process) is terminated if your code contains an error at the specified level or higher, provided such errors are reported to the cob command by the Compiler. This depends on the setting of the WARNING Compiler directive, which controls the level of error reported by the Compiler (see the chapter Directives for Compiler for details of this directive).
Thus, for example, if you set the WARNING directive to force the Compiler to report only unrecoverable, severe and error level errors, but also set the -W flag to abort the cob command if any errors at the information level (or above) are reported, errors only in the categories unrecoverable, severe or error actually causes the cob command to terminate, as warning and information errors are not reported.
Excludes the unresolved text symbol symb
from the
executable output file. It creates a stub routine to satisfy any reference to
symb
, which if called produces RTS error 107:
Operation not implemented in this Run-Time System
It can be used to satisfy undefined symbols to modules that you know are not required (but are referenced), thereby still allowing an executable file to be produced. The resulting file might not actually be any smaller than it would have been if you had not specified this flag. However, setting this flag does ensure that should you try to call any excluded module, you receive a meaningful error message.
See the description of the -I flag earlier in this section for descriptions of valid symbols.
Creates a single statically or dynamically linked executable module from the files input to the cob command. The input file can be any file type except a .gnt file. By default, the name of this module is the base-name of the first object being statically linked. It has no extension.
You also can use this option to produce a full RTS, for example,
cob -xo rts.new
You also might 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. See the section Creating an Executable RTS in the chapter Linking
The CC option to the -x flag enables you to link Cobol and C++ objects into an executable file. Note that this option does not enable you to compile C++ objects; you must use the C++ compiler to do that.
For example, if the local C++ compiler is CC, and you want to link the C++ program cprg and the COBOL program cobprg.cbl, use the following commands:
CC cprg.C cob -x,CC cobprg.cbl cprg.o
The following cob flags are reserved for future use by Micro Focus:
-f
-q
-z
Copyright © 1998 Micro Focus Limited. All rights reserved.
This document and the proprietary marks and names
used herein are protected by international law.
COBOL System Interface (cob) | Descriptions of cob Error Messages |