COBOL System Interface (cob)

Descriptions of cob Error Messages

Chapter 9: 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, .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).

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

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, 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:

• A library specified more than once on the linker line has 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 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.

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

Specify the object module format of any object produced (-b format)

SCO OpenServer Release 5:

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:

• coff
  
  
• ibcs2
  
  
• elf

ibcs2 is an alias for coff. The values for format can take any case.

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 Compiler (-CC cc_option)

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.

Compile No Further Than Statically Linkable Object Module (-c)

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.

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

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 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 an RTS Quickly (-F)

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.

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)

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.

Generate for Animation (-F)

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

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 that you want 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 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:

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.

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.

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

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:

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 /user/grouplib -llib3 -L /user/mylib -llib3

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

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.

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

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

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.

Pass Generate Phase Directive (-N directive)

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.

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 files are being processed, this flag also is passed through to cc.

Specify Output File-name (-o filename)

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.

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

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

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

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:

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:

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 Statically or Dynamically Linked Executable Module (-x[,CC])

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 

Flags Reserved for Future Use

The following cob flags are reserved for future use by Micro Focus:

-f
-q
-z

COBOL System Interface (cob)

Descriptions of cob Error Messages