cob(1) CLIX cob(1)
NAME
cob - Runs the COBOL compiler
SYNOPSIS
cob [flag ... ] file ...
FLAGS
-a Compiles the input file for animation. Any .cbl input
files are compiled to .int suitable for animation (the
animator symbol file .idy will also be produced). This
flag does not specify an end point, only the type of .int
produced by the COBOL compiler.
-c Suppresses the link editing of any statically linked
executable file. This flag does not specify an end point.
It will only have effect if the specified end point would
cause link editing.
-d sym Causes sym to be dynamically loaded if it is referenced.
This flag can be used to specify missing modules (which
are to be loaded dynamically at run time) when producing a
statically linked executable file.
-e epsym Sets the default entry point address for a statically
linked executable file to be that of the symbol epsym.
This flag has no affect unless epsym is defined in a COBOL
module.
-g For use with dbg, symbols are not stripped from the output
file. This flag will also be passed through to cc if any
.c files are being processed.
-i Causes the end point to be reached when all .cbl programs
have been compiled to dynamically loadable .int files.
-k cobolfile Processes cobolfile as if it had a valid COBOL source file
suffix (.cbl). This flag allows COBOL source files
without the recognized suffix be compiled without having
to alter their filename.
-lx Passes through to ld, keeping the relative ordering. This
flag causes ld to search the library libx.a for external
routines. A library is searched when its name is
encountered, so the placement of -l flags is significant.
By default, libraries are located in /lib and /usr/lib
(see -L on how to specify alternative search paths).
+lx Passes through to ld, keeping the relative order. This
2/94 - Intergraph Corporation 1
cob(1) CLIX cob(1)
flag causes ld to search the library libx.a for external
routines. A library is searched when its name is
encountered, so the placement of a +l is significant. By
default, libraries are located in /lib and /usr/lib (see
+L on how to specify alternative search path).
-m symb=newsym Maps unresolved symb onto newsym. Creates a stub routine
to satisfy any references to symb. The stub routine, if
called, will cause control to be passed to a routine with
entry name newsym, which must be defined. Using this
flag, parts of statically linked executable modules
produced may be mapped onto user-supplied routines or
tailored modules. Possible RTS symbols which may be
mapped are:
lsfile line sequential fixed-length record file handler
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 +L and +l to
specify the library search path and name. This will
insure that references from the COBOL libraries to the new
symbols are correctly located.
-o outfile Specifies the filename of the statically linked module
produced (outfile).
-p Arranges for the compiler to produce code that counts the
number of times each routine is called; also, if link
editing occurs, replaces standard startup routine with one
that automatically calls monitor() at the start and
arranges to write out a mon.out file at normal object
program termination. An execution profile can then be
generated by using prof.
-r Retains relocation entries. Only affects any executable
2 Intergraph Corporation - 2/94
cob(1) CLIX cob(1)
file produced. Any unresolved references do not cause an
error to be reported, but are assumed to be resolved in a
subsequent link (which can be done using the system linker
ld alone).
-u Causes the end point to be reached when all .cbl programs
have been compiled to dynamically loadable .gnt files.
-v Causes cob to execute in verbose mode.
-x Causes the end point to be reached when all programs have
been compiled and link edited to produce a statically
linked executable file. By default, the output filename
will be the basename of the first object being statically
linked.
-A flag Passes flag to the as command.
-Cx flag Passes flag to the compiler x. If no compiler ID (x) is
specified, then flag is passed to the COBOL compiler. If
the compiler ID is C, then flag is passed to the C
compiler with cc.
-F Causes fast creation of a statically linked executable
file with dynamic load support. When a statically linked
executable file which is to support dynamic loading of
COBOL modules is being produced, all entry points and
external data (both from C and COBOL modules) are made
available to dynamically loaded files. The cob command
does this by creating an entry for each in a loaded table
(ldtab). With the -F flag, only the names found in
modules on the command line and a default list (from
COBDIR/coblib/cobfsym) are used, thus reducing the time
needed to create a statically linked executable file. For
example, any symbols due to objects from archives are not
included. If a reference from a dynamically loaded file
is made to any name not in the loaded table (even if it is
included in the linked executable module) then rts error
173 Called program file not found in drive/directory may
be produced. See +F for how to specify additional symbols
for the loaded table. This flag cannot be used with the
-U flag.
+F symbol Causes the fast creation of a statically linked executable
file with dynamic load support. This flag is identical to
-F, except it expects an argument of a symbol name to add
to the load table (ldtab). (See the description for -F.)
Symbol will be added to the ldtab, so that any call to a
module of that name will cause control to be passed to the
function identified by symbol. Note that a link time an
2/94 - Intergraph Corporation 3
cob(1) CLIX cob(1)
Undefined symbol(s) error will occur if symbol is not part
of the statically linked executable file being produced.
This flag cannot be used with the -U flag.
-L dir Passes through to ld, keeping the relative order. This
flag changes the search algorithm for libraries which are
not specified with an absolute pathname. By default, the
directories /lib and /usr/lib are searched. Any dir
specified with this flag will be searched first. This
flag only effects libraries specified with the -l or +l
flags.
+L dir Passes through to ld at the end of ld flags. This flag
changes the search algorithm for libraries which are not
specified with an absolute pathname. By default, the
directories /lib and /usr/lib are searched. Any dir
specified with this flag will be searched first. This
flag only effects libraries specified with the +l flag.
-N flag Passes flag to the COBOL native code generator.
-O Invokes the object code optimizer, for use when all
debugging has taken place and maximum performance with
minimum run time checks is required. Its exact operation
is target dependent, but will at minimum imply the COBOL
compiler and native code generator get passed the flag
NOBOUND (NOCHECK). This flag will also be passed through
to the cc command if any .c files are being processed.
-P Causes the COBOL compiler to produce a listing file .lst
for each .cbl input file. Any errors detected by the
compiler will be reported both on stderr and in the
listing file (at the point at which the error was
located).
-Q flag Passes flag to the command ld.
-U Causes any unresolved reference to be treated as a COBOL
program to be dynamically loaded rather than being a fatal
error at link time.
This flag cannot be used with the -F or +F flags.
-V Reports the version number of any of the invoked
components. This flag is passed to system programming
commands such as cc and ld if they are invoked.
-W err-level Causes cob to terminate after the COBOL compiler err-level
has been exceeded. Possible values for err-level are
informational, warning, error, severe, or unrecoverable
4 Intergraph Corporation - 2/94
cob(1) CLIX cob(1)
(the first letter is all that is required). The default
err-level is severe.
-X symb Excludes symb from the executable output file. Creates a
stub routine to satisfy any references to symb which, if
called, will give a run time error to the effect that symb
is not loaded. This flag reduces the size of statically
linked executable files produced by excluding modules
known not to be required but which are referenced.
Possible Run-Time System (RTS) symbols which may be
excluded are as follows:
ANIM animator support module
COBCOMMS
COBOL ANSI communications module
DYNLOAD
modules to provide dynamic loading
INTERPRETER
the interpreter for .int files
PROFILE
COBOL profiler support module
USERCALL
user defined call by number routine support
DESCRIPTION
The cob command is an interface to the COBOL compilation system. It
causes the named files to be processed with the aim of producing an
executable COBOL program.
There are two basic types of executable COBOL programs, and cob provides a
means of creating a mixture of either of these types of programs:
statically linked a CLIX COFF executable file.
dynamically loaded a COBOL intermediate code file or a COBOL generated
code file.
A dynamically loaded file is invoked by a statically linked executing
program. The statically linked program calls the dynamic loader, which
loads the dynamically loaded file from disk into memory and executes it.
Files input to cob are recognized by their suffix; any unrecognized files
are saved for use at link time because they are assumed to be valid linker
flags or input files. Recognized suffixes are as follows:
2/94 - Intergraph Corporation 5
cob(1) CLIX cob(1)
.cbl/.cob/.CBL COBOL source
.int COBOL intermediate code
.gnt dynamically loadable generated code
.c C source
.s assembler source
.o object module
.a archive of object modules
An input file can be processed in steps (compilation, native code
generation, link editing) until the specified end point is reached.
.cbl -> .int compile
.int -> [.gnt] code generate for dynamic loading
[.o] code generate for static linking
.gnt no further processing possible
.c -> .o passed to cc
.s -> .o passed to system assembler
.o [[.o]..] -> a.out passed to ld
.a passed to ld
The default end point is reached when all COBOL source files have been
compiled for debugging with the animator (the COBOL debugger). Other end
points can be specified by use of cob flags.
If any of the input files are below the desired end point, such as when
the end point is a dynamically loadable file and a .o input file is
specified, cob assumes that the input files have been specified because
they are required. The cob command will statically link them to the
dynamic loader to produce a static run time library which can be used to
load and run any dynamically loadable files.
If the end point is a statically linked executable file (cob flag -x),
then files with suffix .cbl can be compiled (.cbl -> .int), object code
generated (.int -> .o), and then linked (.o -> a.out) to produce a
statically linked executable file. A dynamically loadable generated code
file may be produced instead (-u) by compiling (.cbl -> .int) and code
generating (.int -> .gnt). Note that the first step in this procedure is
the same as producing a statically linked executable file and so may be
omitted if a valid .int file already exists.
Any temporary files produced at any of the intermediate stages are
unlinked once used, but .int and .o files are always kept.
A dynamically loaded or statically linked COBOL program may access (using
the COBOL CALL verb) any other static linked module, whether written in
6 Intergraph Corporation - 2/94
cob(1) CLIX cob(1)
assembler, C, COBOL or any other language which complies with CLIX COFF
and conforms to both the C function calling conventions and to any valid
dynamically loadable file.
Invocation
All input files are recognized by their suffix. All the COBOL system
tools (the compiler, ncg, and so on) are located in one directory. The
default path of this directory is /usr/lib/cobol, but the environment
variable COBDIR, if set, may be used to specify an alternative path.
Once invoked, the cob command reads the startup file COBDIR/cobopt, which
contains the system default flags in the following format:
compiler: <COBOL compiler flag>
ncg: <COBOL native code generator flag>
set <name>=<value>
<cob flag> [[<cob flag>]..]
If a line begins with one of the recognized identifiers it will be
processed. Any line which does not begin with a recognized identifier
will be treated as a comment. The recognized identifiers are as follows:
compiler The rest of the line is passed to the COBOL compiler.
ncg The rest of the line is passed to the COBOL Native Code
Generator.
set Allows environment variables to be assigned values.
<cob flag> The line is processed as part of the command line.
The contents of COBDIR/cobopt affect the operation of the COBOL on the
whole system. It should be altered only after due consideration of the
implications.
The environment variable COBOPT may contain further flags (which may
supplement/override those specified in COBDIR/cobopt) or may be used to
specify the path of a file containing further flags. Either use must be
in the format shown above.
Finally, the flags passed to the cob command on the command line are
processed (they may supplement/override those already specified in
$COBDIR/cobopt and COBOPT).
The cob command may also be passed flags directly from embedded $SET flag
statements in the COBOL source code, see the COBOL Operating Guide for
details.
All flags can use the syntax flag=param rather than flag(param); cob will
map any such syntax onto the flag(param) syntax acceptable to the COBOL
2/94 - Intergraph Corporation 7
cob(1) CLIX cob(1)
components. To pass = to the COBOL components, == should be used.
Any flags which are not recognized will be passed to ld. If any ld flags
other than those specified above have an argument, use -Q "..." to insure
they are passed to ld as an flag with an argument rather than treated as
separate flags.
Creation of statically linked module
Any object files and flags are passed to ld in the order they are
specified on the command line (except for the +l and +L flags detailed
above). Any input files to cob that are not .o files are replaced (in the
same logical position on the command line) with their mapped .o files.
Only input files which map to .o files or are already .o files are passed
to ld. The default entry point is the basename of the first input file.
The cob command creates its output files in the current directory. Any
temporary files are created under /usr/tmp unless the environment variable
TMPDIR is set and specifies a valid pathname.
EXAMPLES
1. To compile the COBOL file, file.cbl, to a dynamically loadable file
and produce a file suitable for animation, enter the following:
cob file.cbl
or
cob -ia file.cbl
This compiles file.cbl to file.int, a dynamically loadable file. The
cob command also produces an animator symbol file, file.idy.
2. To display more information during a compile, enter the following:
cob -ivP file.cbl
This compiles file.cbl to the dynamically loadable file.int, but it
displays information about the compile and produces a log of compile
messages and information in the file file.1st.
3. To compile a COBOL source file, enter:
cob -uv -k file.src
This compiles file.src into a COBOL source file and produces the file
file.gnt, which is dynamically loadable.
4. To compile a set of files and create a statically linked executable
file, enter the following:
8 Intergraph Corporation - 2/94
cob(1) CLIX cob(1)
cob -gx -o sample -d init_routine file.cbl file2.c file3.s
This compiles the files given and creates the statically linked
executable file, sample, including debug symbols. It also specifies
that the function ``init-routine'' is to be dynamically loaded when it
is referenced rather than included as part of the statically linked
executable file.
FILES
file.cbl Input file.
file.cob Input file.
file.CBL Input file.
file.c Input file.
file.o Input or output file.
file.a Input file.
file.s Input file.
file.int Input or output file.
file.gnt Output file.
file Output file.
a.out Output file.
cobol COBOL compiler.
ncg COBOL native code generator.
libcobol.a COBOL library.
main.s COBOL main startup template.
liblist Default list of COBOL libraries to search.
cobver COBOL version ID.
DIAGNOSTICS
Any of the components used by cob may return their own error messages.
The cob command may report various errors, most of which will be self-
explanatory. The following errors are worthy of special note:
incompatible flag:____
2/94 - Intergraph Corporation 9
cob(1) CLIX cob(1)
The flags to the cob command are not valid.
____ unknown extension
The input filename does not have a recognized filename suffix.
entry: ____, not found
The specified entry point is not defined in any module.
entry defined: ____, conflicting main found in: ____
The symbol main is defined in a module other than the specified
entry point module.
entry: ____, does not have main defined
The specified entry point module (which is a non-COBOL module) does
not define main. This is the compulsory entry point for any non-
COBOL module.
invalid entry point name: ____
The specified entry point symbol is not a valid Symbol name. A
valid Symbol name may consist of the characters a-z, A-Z, 0-9,
underscore (_) and dot (.). A name may not begin with a digit.
EXIT VALUES
The cob command exits with a nonzero exit value when errors are
encountered. On successful completion the exit value is 0.
RELATED INFORMATION
Commands: acc(1), cc(1), ld(1), as(1), prof(1), dbg(1), sdb(1)
Functions: monitor(3)
COBOL Operating Guide
10 Intergraph Corporation - 2/94