Chapter 11: Descriptions of cob Flags

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, callable shared objects, .int, .gnt and .o files, as well as system executables) depends upon the type of file input and the options specified to the cob command. cob output files are by default 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).

11.1 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.

Pass Option to Assembler (-A as_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 information files (with extension .idy), both of which are used by Animator (see the chapter Starting Animator in your Utilities Handbook for information on these files.)

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 system 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

Pass Syntax-check Phase Directive to the Compiler (-C directive)

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.

Pass Option to the C or C++ Compiler (-CC cc_option)

Passes cc_option to the C or 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 or C++ compiler itself. This is because the system assumes that if you are using the cob command rather than cc to compile a C or C++ program, you want to link the C or C++ program to COBOL programs before it is run. To do this, cob needs the .o file output by the C or C++ compiler once it has compiled the C or C++ program. cob can then take the resulting .o file and link it with other object modules to create a callable shared object, shared library or system 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.

Compile No Further Than Linkable Object Module (-c)

Suppresses the link editing of any linked executable module, so the object modules can subsequently be 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, -z or -Z cob flags 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 linked executable module, to specify any missing modules that are to be loaded dynamically at run time.

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 linked module is the basename of the first file input to the cob command. If you are linking to a system executable (-x cob flag) and 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 "".

Create Information for Symbolic Debugger (-g)

When compiling, the ANIM directive is passed to the compiler to produce .int, .gnt or .o code that can be used by the Animator.

When linking, the linker creates additional information needed for the use of a symbolic debugger such as dbx. With this flag set, no symbols are stripped from the output file. This flag is passed through to the C or C++ compiler if any .c or .C files respectively are being processed, so it is useful if your program contains some C or C++ functions that you want to debug.

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 is pulled in along with any other objects that are referenced. This flag can be used to include support from an archive; for example:

cob -xo rts32 -e "" -I func1 -I func1 libmine.a 

Compile to Intermediate 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 files (with the file extension .int). These files can then be run without any further processing.

Recognize COBOL Source File with Non-standard Filename 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 filename.

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 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.

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:

  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  /usr/grouplib -llib1 -L /usr/mylib -llib1

  7. -L /lib -llib1 -L /usr/lib -llib1

  8. -L $LD_LIBRARY_PATH -llib3

  9. -L /user/grouplib -llib3 -L /user/mylib -llib3

  10. -L /lib -llib3 -L /usr/lib -llib3

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.

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. 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.

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 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.

Map Symbol to New Symbol (-m symb=newsym)

Maps unresolved symbol symb to newsym, which must already have been defined in a COBOL module; that is, any call to symb will go to newsym.

You also can use this flag to map parts of 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 File Handler API in your File Handling book 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.

Pass Generate Phase Directive (-N directive)

Passes the specified option to the Compiler'>directive is one or more of the generate phase directives listed in the chapter 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 passes the NOCHECK directive to the Compiler. If any .c or .C files are being processed, this flag also is passed through to cc or the C++ compiler.

Specify Output File-name (-o filename)

Changes the default name of the linked executable module created using the -x, -z or -Z option to the filename specified. The default filename for system executable files is the basename of the first file entered to the cob command. The default filename for callable shared objects is the basename of the first file entered to the cob command with .so appended. The default filename for shared library files is the basename of the first file entered to the cob command with a prefix lib and a suffix .so appended.

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 the 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 or C++ compiler. If linking to a system 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 linked executables.

Pass Option to System Linker (-Q ld_option or -Q,1 ld_option or -Q,2 ld_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 linked executable module 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.

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.

Create Multi-threading Program (-t)

Creates multi-threading programs that use the multi-threading run-time system. It passes the REENTRANT Compiler directive to the Compiler and appropriate options to the C and C++ compilers if required, and selects the multi-threading libraries.

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 when creating a system executable, or cause a fatal error at run-time for callable shared objects.

Compile to Generated Code for Unlinked Environment (-u)

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.

If the -g flag is also specified, the resulting generated code contains debugging information so that it can be debugged with Animator.

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 linked to create an executable RTS. Dynamically loaded programs can call any of the modules in the linked executable RTS 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.idy, a.gnt
cob -u b.cbl b.int, b.idy, b.gnt
cob -u a.int a.gnt
cob -u tmp/b.int b.gnt
cob -ug a.cbl a.int, a.idy, a.gnt

Report Version Number (-V)

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).

Set Verbose Module (-v)

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.

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 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.

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 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.

Process to System Executable File (-x[,CC])

Creates a system executable file 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 linked. It has no extension.

You also can use this option to produce a full RTS, for example,

cob -xo rts.new

The CC option to the -x flag enables you to link COBOL and C++ objects into an executable file. If C++ (.C) source files are specified, the C++ compiler is invoked to compile them to object code first.

For example, if you want to link the C++ program cprg.C and the COBOL program cobprg.cbl, use the following commands:

cob -x,CC cobprg.cbl cprg.C 

Compile to Self-contained Callable Shared Object (-y)

Processes a source file to a self-contained callable shared object. We recommend that you use this only for creating NSAPI programs or DB2 stored procedures. For information about creating NSAPI programs see the chapter Building NSAPI Programs in your Internet Applications book. For information about creating DB2 stored procedures see the section Client DB2 Applications and Stored Procedures in the chapter DB2 in your Database Access book.

Compile to Callable Shared Object (-z[,U][,CC])

Compiles the COBOL source code files (.cbl, .CBL or .cob) into intermediate code and then generates them to object code (.o) files, and then links these to create dynamically loadable callable shared objects. These files have the file extension .so.

If the -g flag is also specified, the resulting callable shared object contains debugging information so that it can be debugged with Animator.

You can supply intermediate code files to the cob command instead of COBOL source code files; these are generated to object code. You can also supply object module files (.o) to the cob command; these are linked using the system linker (ld) to create the dynamically loadable callable shared object.

The U option specifies that an error message should be issued if there are any undefined symbols.

The CC option to the -z flag enables you to link COBOL and C++ objects into a callable shared object. If C++ source files (.C) are specified, the C++ compiler is invoked to compile them to object code first.

For example, if you want to link the C++ program cprg.C and the COBOL program cobprg.cbl, use the following command:

cob -z,CC cobprg.cbl cprg.C 
Examples:

The following examples illustrate the types of processing available using the -z flag:

cob Command line
Output Files
cob -z  tmp/a.cbl a.int, a.so
cob -z b.cbl b.int, b.so
cob -z a.int a.so
cob -z c.o c.so
cob -zg a.cbl a.int, a.idy, a.so

Process to library file (-Z[,CC])

Creates a shared library file 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 basename of the first object being linked with a prefix of lib and the filename extension .so (or .sl on HP/UX).

The CC option to the -Z flag enables you to link COBOL and C++ objects into a library file. If C++ (.C) source files are specified, the C++ compiler is invoked to compile them to object code first.

For example, if you want to link the C++ program cprg.C and the COBOL program cobprg.cbl, use the following command:

cob -Z,CC cobprg.cbl cprg.C

Flags Reserved for Future Use

The following cob flags are reserved for our future use:

-f
-q


Copyright © 2002 Micro Focus International Limited. All rights reserved.
This document and the proprietary marks and names used herein are protected by international law.