HP 3000 Manuals HP 3000 Manuals
Descriptions of Flags
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. Unless otherwise indicated, there must
be a space between a flag and its option.
Pass Option to Assembler (-A option)
Passes the specified option to the UNIX system assembler (as).
Compile for Animation (-a)
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 for details on using Animator.)
Any object module files (with extension .o) 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 allows you to animate programs that
call, or are called by, programs which 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, assuming that the current directory is referenced in
the PATH environment variable. To animate myfile.int, use the commands:
COBSW=+A
export COBSW
c myfile.int
Select System Linker's Binding Mode (-B mode[=lib])
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, will be 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 libfhutil, or the operating
system library libc, etc) 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. 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:
* a library specified more than once on the linker line will have
the same binding mode on each occasion.
* if 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 for the COBOL
library libscreen, which is to be statically linked. Thus, the shared
object (.so) versions of libraries will be chosen over corresponding
archive (.a) versions, except for library libscreen, where the archive
version is chosen even if there is a shared object version.
Select System Linker's Binding Mode and Pass to System Linker After COBOL
Libraries (+B mode[=lib])|
Has the same effect as -B except that relative ordering is not preserved.
+Bmode is converted to -Bmode 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 -Bmode 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 could also 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.
Pass Option to the COBOL Compiler (-C option)
Passes option to the COBOL Compiler, where option is one or more of the
Compiler directives listed in the appendix Directives for Compiler.
Pass Option to the C Compiler (-CC option)
Passes 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 attempt to use the -CC flag
to pass options that the Compiler normally would try to pass to the
system linker.
Compile No Further than Statically Linkable Object Module (-c)
Supresses the link editing of any static linked executable, so that the
object modulescan subsequently be statically linked. This option does
not specify an end point and so will have effect only if the specified
end point would cause link editing; for example, if the -x cob flag had
been specified.
Dynamically Load Symbol (-d symb)
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, in order to specify any missing modules
which 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).
Set Initial Entry Point (-e epsym)
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 wish 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.
Create an RTS Quickly (-F)
Allows the fast creation of a statically or dynamically linked executable
modulewith 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 which is not in ldtab (even if it is included in the
linked executable), then you will 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.
Create an RTS Quickly and Add List of Symbols to a Linked Data Table
(-F,fname)
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.
Create an RTS Quickly and Add Symbol to a Linked Data Table (+F symb)
Allows 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 will cause control to be passed
to the function identified by symb. At link time, the error "undefined
symbol(s)" will occur if symb is not part of the static linked executable
being produced.
You cannot specify this flag if you set the -U flag.
Create Information for Symbolic Debugger (-g)
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 which you wish to debug. It also passes the ANIM directive to
the Compiler.
Include Symbol in Executable File (-I symb)
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 which are referenced, is pulled in. For example, you need to
include -I COBWIN1 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 (the default), as
certain modules which are 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
-------------------------------------------------------
CCINAMP CCI modules for named pipe support
CCITCP CCI modules for TCP support
CICS Pointer conversion utilities for
OS/VS COBOL
COBWIN1 Windowing support
DSRTNS Dialog System RTS support
FHREDIR Fhredir file handling redirector
fhutil File handler
PANELS2 Panels Version 2 support
SESSION Session handling
Compile to .int Code for Unlinked Environment (-i)
Compiles the COBOL source code (.cbl, .CBL or .cob) files input to the
cob command into dynamically loadable intermediate code (.int) files.
These files can then be run without any further processing.
Recognize COBOL Source File with Non-standard File-name Extensions (-k
cobol-file)
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 file-name.
Pass Option to System Linker Changing Search Algorithm and Maintaining
Relative Ordering (-L dir)|
Changes the order in which the system linker searches for libraries which
were specified with the -l cob flag. -L options affect only those -l
options which 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 specificed is significant as directories will be
searched in that order.
On systems that support dynamic linking, paths in the environment
variable LD_LIBRARY_PATH 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:
1. object.o
2. -L $LD_LIBRARY_PATH -llib2
3. -L /usr/grouplib -llib2
4. -L /lib (or /usr/ccs/lib) -llib2 -L/usr/lib -llib2
5. -L $LD_LIBRARY_PATH -llib1
6. -L /user/grouplib -llib1 -L/usr/mylib -llib1
7. -L /lib -llib1 -L/usr/lib -llib1
8. -L $LD_LIBRARY_PATH -llib3
9. -L /lib -llib3 -L/user/grouplib -llib3, -L/user/mylib, -llib3
10. -L /usr/lib -llib3
The complete search path for every library would be searched only if a
status of "file not Found" is returned on earlier paths.
Pass Option to System Linker After All Other Options Changing the Search
Algorithm (+L dir)|
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.
Pass Option to System Linker Maintaining Relative Ordering (-l lib)
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 specificed is significant as
directories will be 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:
1. -llib1 obj1.o
2. -llib3 obj2.o
3. -llib2
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.
Pass Option to System Linker After all Other Options (+l lib)
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 will
be 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.
Map Symbol to New Symbol (-m symb=newsym)
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 that if this new routine is called, control is
passed to the routine which has the entry name newsym. This flag allows
you to "dummy out" unwritten optimized routines into one general purpose
routine, provided that 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 which may be mapped are:
Symbol Module
-------------------------------------------------------
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 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 handlersupplied 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 for details). Additionally, you can use the -m
flag to link with the RTS a version of C-ISAMother than the version
supplied with your Micro Focus COBOL system.
Pass Option to Native Code Generator (-N option)
Passes the specified optionto the Native Code Generator. option is one
or more of the Generator directives listed in the appendix Directives for
Compiler.
Enable Optimization (-O)
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 will pass the NOBOUND directiveto the Compiler and Native Code
Generator. If any .c files are being processed, this flag also is passed
through to cc.
Specify Output File-name (-o file-name)
Changes the default name of the static linked executable module created
using the -x option to the file-name specified. The default file-name is
the base-name of the first file entered to the cob command.
Produce Listing File (-P)
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).
Pass Flag to C Compiler to Use Profiling Routines (-p)
Passes the option -p to the C compiler. If linking to produce a static
or dynamic linked executable module, it causes cob to use profiling
startup and termination routines which 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.
Pass Option to System Linker (-Q option or -Q,1 option or -Q,2 option)
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 in order to support dynamic loading and reference to C
external data. Specifying -Q option passes the options to both linker
passes (that is, calls of the command ld). Specifying -Q,1 option passes
the options to only the first linker pass. Specifying -Q,2 option passes
the options to only the second linker pass.
The -Q,2 option flag cannot be used with the -F and +F flags.
You must use a separate -Q flag for each option, and any options which
begin with hyphens must be enclosed within 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.
Dynamically Load Unresolved Reference (-U)
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.
Compile to .gnt Code for Unlinked Environment (-u)
Compiles the COBOL source code files (.cbl, .CBL or .cob) into
intermediate code (.int) and then code generates them to dynamically
loadable native code (.gnt) files.
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 tmp/a.int, tmp/a.gnt
cob -u b.cbl b.int, b.gnt
cob -u a.int a.gnt
cob -u tmp/b.int tmp/b.gnt
Report Version Number (-V)
Sends to the screen the version number of any of the COBOL system
components which have been invoked. This option is passed to the system
programming utilities (for example, cc and ld).
Set Verbose Module (-v)
Sends to the screen messages output by the Compiler and the Native Code
Generator 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.
Control Error Level for cob Termination (-W err-level)
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 is dependent upon
the setting of the WARNING Compiler directive, which controls the level
of error reported by the Compiler (see the appendix 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 will actually cause the cob command to
terminate, as warning and information errors will not be reported.
Exclude Symbol from the Executable Output File (-X symb)
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 will produce RTS error 107:
Operation not implemented in this Run-Time System
It can be used to satisfy undefined symbols to modules which you know are
not required (but which 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 attempt to call
any excluded module, you will receive a meaningful error message.
See the description of the -I flag earlier in this section for
descriptions of valid symbols.
Process to Statically or Dynamically Linked Executable Module (-x)
Creates a single statically or dynamically linked executable modulefrom
the files input to the cob command. The input file can be any file type
except for 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 can also use this option to produce a full RTS, for example,
cob -xo rts.new
You may also need to specify the -I symb flag for any additional support
you require for your RTS. For example, you need to include -I COBWIN1 in
the cob command if you want to create a new RTS that includes windowing
support.
An alternative method of creating an RTS is to use the script file mkrts.
Running mkrts builds a new RTS, including modules that might not be
included if you used the above command.
To use mkrts, you must log in as super user, then change directory to
$COBDIR/src/rts. Once in this directory issue the following command:
sh mkrts
This results in the creation of a new RTS using the same modules as your
original RTS.
Flags Reserved for Future Use
The following cob flags are reserved for future use by Micro Focus:
-f
-q