PreviousLinking to System Executables Descriptions of cob FlagsNext

Chapter 10: COBOL System Interface (Cob)

This chapter describes how to use the Cob utility. This utility provides the interface to the Compiler and system linker. This interface enables you to handle all the phases involved in the production of an executable program.

10.1 Introduction

The Cob utility enables you to handle all the phases involved in the production of an executable program by providing the interface between your COBOL source program and the following COBOL system components:

It also provides an interface to the C++ compiler, cc (the C compiler) and as (the Assembler).


Note: If you are using the 64-bit version of Server Express the names of tools might vary. For more information see the chapter Working in 32-bit and 64-bit Modes.


10.2 Using Cob

You start and control the Cob utility using the cob command. cob causes the files named on its command line to be processed with the aim of producing modules that can be linked or run.

There are five basic types of executable COBOL program; the cob command provides a straightforward means of creating a mixture of any of these types of program. The executable files types are:

Callable shared object files, intermediate code files (.int files) and generated code files (.gnt files) are dynamically loadable, and do not have to be linked into a system executable to be executed.

Shared libraries are system linkable files that can be linked into executable files. They cannot be directly executed themselves.

System executable files are files in an operating system format that are directly executable. They are loaded by the operating system, which creates a new process in which to run them.

For detailed information on the types of executable file, see the chapter Packaging Applications.

The type of file output by cob depends on the type of file you input to it and the options you specify to the cob command. The file types recognized by cob are identified by their extensions as follows:

Extension
File Type
.cbl or .CBL or .cob COBOL source file
.int COBOL intermediate code file
.gnt Dynamically loadable generated code file
.s Assembler source file
.c C source file
.a Archive of object module files
.so Shared library file
.o Object module file
.C C++ source file

Cob assumes that any unrecognized options are either input files or valid linker options to be saved and used at link time. In this way, any archive files you supply to the cob command are passed to the linker, which pulls out only the referenced files from the archive.

You can use COBOL source files with extensions other than those listed above. To do so, you must specify the -k cob flag to identify them to cob (see the chapter Descriptions of cob Flags for details).

10.2.1 Invoking the Cob Utility

To invoke the Cob utility, enter the following at the UNIX system prompt:

cob [options|filename] ...

where the parameters are:

options Either one cob option or a group of cob options comprising one or more cob flags. See the section Specifying cob Options for details on the format of cob options.
filename The name of an input file. These files can be any mixture of COBOL source code (.cbl, .CBL or .cob), intermediate code (.int), linkable object code (.o or .so), C source (.c), C++ source (.C), Assembler source (.s), or archive (.a) files.

10.2.2 Specifying cob Options

A cob option takes the form:

flag-intro flag-letter [parameter]

A group of cob options is equivalent to a separate option for each flag-letter with all options having the same intro. The parameter, if present, only apply to the last option. It takes the form:

flag-intro flag-letter[flag-letter]... [parameter]

where the parameters are:

flag-intro The hyphen (-) or the plus (+) character
flag-letter A letter (or occasionally letters) selected from those listed in the section cob Flags later in this chapter, that flags the required option.
parameter An optional string of characters that details exactly how the flagged option is to behave. The parameter cannot contain a space or tab character unless that character is contained in single (') or double (") quotation marks.

There must be no spaces between flag-intro and flag-letter or between two adjacent flag-letters but there can be one space between the last flag-letter and the parameter if it is present. (For example -xve "" in which "" represents a null parameter). The flag-intro must always be preceded by a space character.

10.2.2.1 Option Configuration

You can specify cob options in a number of ways, and the method used determines the order in which cob processes them. The cob command processes options from left to right for each method of specifying them. In general, if an option appears more than once, cob uses the setting that it processed last for that option. Some options, such as -C and -N that take Compiler directives, are cumulative.

At start-up, the cob command searches for options in the following sequence of locations:

  1. System default options in the file $COBDIR/etc/cobopt

  2. User default options in the environment variable COBOPT

  3. Execution-time options on the cob command line

You might need to set options as a system or user default and then to unset them again in specific instances. By specifying a hyphen after the flag letter with no intervening space, you can unset the following options: -c, -P and -U.

Options specified on the cob command line pass through the UNIX shell that carries out special processing on certain characters such as space, asterisk (*), parentheses (), single (') and double (") quotation marks before passing them to cob. If you need to pass these characters unchanged as part of an option, you must escape the shell processing. Under the UNIX shell this can be done by preceding the character with a backslash (\) or enclosing it in a pair of single or double quotation marks (see your UNIX system documentation for details of shell processing).

However, for your convenience cob enables you to use the syntax mode=setting in place of either "mode(setting)" or mode\(setting\) so enabling you to avoid these characters. The cob command converts any syntax using the equals sign (=) into the form "mode(setting)". To pass an actual equals sign (=) to the COBOL components, you must use two equals signs together (==).


Note: The cob command treats the special characters single and double quotation marks in exactly the same way when used in an option, regardless of whether the option was specified on the command line or in one of the other locations. A parameter enclosed in a pair of quotation marks must not exceed 128 characters.


Example:

Assuming the following line in $COBDIR/etc/cobopt:

-U -P -C "ans85 noalter warning=1"

specifying the cob command line:

cob -xU -C alter -C warning=2 prog.cbl

or the exact equivalent:

cob -xU -C "alter warning=2" prog.cbl

passes the COBOL source file prog.cbl to the Compiler with the final directive settings of ANS85 ALTER LIST"prog.lst" WARNING"2". An executable program prog is built, with any unresolved symbols being dynamically loaded at run time and flagged as missing at link time.

10.2.2.1.1 The $COBDIR/etc/cobopt File

System-wide default options are defined in the file $COBDIR/etc/cobopt. This is the file the cob command reads when first invoked. Each line of this text file should correspond to one of the following formats:

[set environment-variable=value]
[options] ...
[cobextn: .ext [.ext] ... ]

where the parameters are:

environment-variable Any one of the environment variables supported by the COBOL system (see the appendix Micro Focus Environment Variables for details).
value The value to which you want to set the specified environment variable.
options Either one cob option or a group of cob options comprising one or more cob flags. See the start of the section Specifying cob Options for details on the format of cob options.
.ext A filename extension that, in addition to the standard ones of .cob, .cbl, or .CBL, denotes a file that cob should treat as a COBOL source file. The extension must begin with a period, and if more than one is specified on one line they must be separated by a space or tab character. You can use more than one cobextn line.

If a line does not begin with one of the identifiers set or cobextn:, it is taken as an options line.


Note: The contents of the file $COBDIR/etc/cobopt affect the operation of COBOL for all users using the same $COBDIR; you should alter the file only after careful consideration of the implications.


Example

Assuming the following two lines in $COBDIR/etc/cobopt:

cobextn: .AD  .FD 
-N "nobound" -C ans85

specifying the cob command line:

cob -u a.FD b.AD

passes the COBOL source files a.FD and b.AD to the syntax-check phase of the Compiler to be translated, under the ANS85 directive, into intermediate code. The intermediate code is then passed in turn to the Compiler's generate phase to be translated, under the NOBOUND directive, into generated code.

10.2.2.1.2 The COBOPT Environment Variable

User default options are defined using the COBOPT environment variable. COBOPT can either contain options that supplement or override the system default options defined in $COBDIR/etc/cobopt, or it can specify the path of a file that contains such options. The options can extend over more than one line and each line must have the same format as described for the file $COBDIR/etc/cobopt (see the section The $COBDIR/etc/cobopt File).

The COBOPT environment variable can be set to a value that includes several lines by enclosing the entire value in single (') or double (") quotation marks that tells the UNIX shell to process each line as part of the one value. Under the Bourne shell, the Enter key can be typed to indicate the line-break. However, other types of shell might need a different way of showing the line-break. If you want to include a double quotation mark in the value, then remember to escape shell processing, for example by preceding it with a backslash (\) character.

See your UNIX system documentation for details of setting environment variables and shell processing.

You can include any valid cob command line in the COBOPT environment variable. If the line includes the -v cob flag, the whole line is echoed to the screen when it is passed to cob (see the chapter Descriptions of cob Flags for details on -v).

Examples:

Specifying COBOPT as follows:

COBOPT="set COBCPY=/usr/lib/cblcpy:$COBDIR/cpylib:$HOME/mylib::
-N nobound -C \"ans85 noalter list\"
cobextn: .AD .FD"
export COBOPT

causes cob to set the environment variable COBCPY for the duration of the cob command, it passes the directives ANS85 NOALTER LIST to the Compiler's syntax-check phase and passes the directive NOBOUND to the Compiler's generate phase. Note that $COBDIR and $HOME get expanded by the shell if the double quotation marks are used but not if single quotation marks are used.

Specifying COBOPT as follows:

COBOPT='-C "copyext=CPY,cpy nooptional-file" -N "nobound"'

causes cob to pass the directives COPYEXT"CPY,cpy" and NOOPTIONAL-FILE to the Compiler's syntax-check phase and the NOBOUND directive to the Compiler's generate phase.

10.2.2.1.3 The cob Command Line

Execution-time options (that is when cob executes, not when the application runs) are specified on the cob command line as described in the section Invoking the cob Command. Options given on the cob command line supplement or override any already specified in the $COBDIR/etc/cobopt file or COBOPT environment variable.

You can specify on the command line any cob options listed in the section cob Flags later in this chapter and described in more detail in the chapter Descriptions of cob Flags.

Example

Assuming neither $COBDIR/etc/cobopt nor $COBOPT exist, specifying the following on the cob command line:

cob -xve "" -o my_rts -C xopen prog.cbl prog2.c

passes the XOPEN directive to the Compiler and instructs cob to compile the COBOL source file prog.cbl and the C source file prog2.c and to link the result into a system executable file named my_rts that, when run, expects the name of the program to run to be given on its own command line. The cob utility also gives verbose notification of its progress.

See the section Command Line Examples later in this chapter for further examples.

10.2.3 cob File Processing

While creating an executable module, the cob command passes each input program through a series of steps, each of which transforms the program from one file type into another file type. Thus, an output file from one step can serve as an input file for a subsequent step. These types are characterized by the file extensions as follows:

Input File cob Processing Output File
name.cbl
name.CBL

name.cob
Compile COBOL source code file into intermediate code file name.int
name.int Create generated code file name.gnt
Generate object code file name.o
name.s Pass to system Assembler name.o
name.c Pass C source code file to C Compiler name.o
name.C Pass C++ source code file to C++ Compiler name.o
name.o
libname.a
libname.so

Pass to system linker (ld) to create shared library file libname.so
Pass to system linker (ld) to create callable shared object name.so
Pass to system linker (ld) to create system executable file (also known as an a.out file) name

By default, cob processing ends when all COBOL source files have been compiled for animation; that is, a dynamically loadable intermediate code file (with extension .int) and an Animator file (with extension .idy) have been created. Other end points can be specified by using cob options (see the section cob Flags later in this chapter).

If any of the input files are beyond the desired end point, cob links them with the dynamic loader. This produces a system executable run-time system, that can be used to load and run any dynamically loadable files.

Any temporary files produced at any of the intermediate stages of processing are removed once used, with the exception of any .int and .o files, that are left in the same directory as their input file.

A linked or dynamically loadable COBOL program, can access (using the COBOL CALL verb) any other linked or dynamically loadable module in the application. For details on creating these types of modules, see the chapter Linking to System Executables.


Note: On file systems that support long filenames, you are recommended to keep the length of program source filenames below the entry point name limit. See the chapter Linking to System Executables for further details.


10.2.4 Accessing the COBOL System Components

To access COBOL system components, the cob command must know where they are located. They must all be located in a directory in which a COBOL system has been installed and the directory is represented in this chapter as $COBDIR. The cob command assumes a default $COBDIR directory of /usr/lpp/cobol on AIX, or /opt/lib/cobol otherwise. If your COBOL system has been installed here then you do not need to specify the COBDIR environment variable. If you put the Micro Focus COBOL system software elsewhere, then you must set the COBDIR environment variable to tell cob in which directory to search for the system components. You can choose to install different versions of the COBOL system on your machine, in which case you select which one to use by simply setting its location in COBDIR. For example:

COBDIR=/home/products/cobse10
export COBDIR

specifies that the system components are located in the directory /home/products/cobse10. If the cob command is not on the UNIX search path then you must change the value of PATH. For example:

PATH=$COBDIR/bin:$PATH
export PATH

You should ensure that LIBPATH (on AIX), SHLIB_PATH (on HP/UX systems) or LD_LIBRARY_PATH (otherwise), is set to $COBDIR/lib.

By default, files output by the cob command are put in the current directory. By default, any temporary files created are put in the system temporary directory; however, you can put them elsewhere by setting the TMPDIR environment variable and specifying a valid pathname. See the appendix Micro Focus Environment Variables for details on using TMPDIR.

10.2.5 cob Flags

The following flags can be used with the cob command to specify any action the system components should take while creating an executable module and to determine the type of file output. For full details on the effect of these flags, see the chapter Descriptions of cob Flags.

cob Flag
Function
-A as_option Pass as_option to Assembler (as)
-a Compile for animation. This is the default
-C directive Pass syntax-check phase directive to the Compiler
-CC cc_option Pass cc_option to C compiler (cc)
-c Compile no further than a linkable object module (.o)
-d symb Dynamically load symb
-e epsym Set initial entry point to epsym
-g Create debugging information
-I symb Include symb in executable module
-i Compile to .int code for unlinked environment
-k cobol-file Recognize COBOL source file with non-standard filename extension
-L dir Pass option to system linker, changing search algorithm and maintaining relative ordering
+L dir Pass option to system linker after all other options, changing search algorithm
-l lib Pass option to system linker, maintaining relative ordering
+l lib Pass option to system linker after all other options
-m symb=newsym Map text symb onto newsym
-N directive Pass generate phase directive to the Compiler
-O Enable optimization
-o filename Specify output filename
-P Produce COBOL compilation listing file
-p Pass flag to C compiler to use profiling routines
-Q ld_option or
-Q,1 ld_option or
-Q,2 ld_option
Pass ld_option to system linker (ld)
-q Reserved for future use by Micro Focus
-t Creates multi-threading programs that use the multi-threading run-time system
-U Dynamically load unresolved symbols
-u Compile to .gnt code for unlinked environment
-V Report version number
-v Set verbose mode
-W err-level Control error level for cob termination
-X symb Exclude text symb from the executable output file
-x Process to system executable file
-x,CC Process to system executable file including C++ support
-y Process to a self-contained callable shared object. This should only be used for creating NSAPI programs. See the chapter Building NSAPI Programs in your Internet Applications book for details.
-z Process to callable shared object
-z,U Process to callable shared object and issue error if there are any undefined symbols
-z,CC Process to callable shared object including C++ support
-z,U,CC Process to callable shared object, including C++ support, and issue error if there are any undefined symbols
-Z Process to shared library
-Z,CC Process to shared library, including C++ support

Any options that are not recognized are passed to the system linker (ld). However, we recommend you use the -Q flag to explicitly pass options to the linker. Any linker flags that take parameters must be passed using the -Q flag.

cob flags -c, -P and -U are binary global options (that is, they select features that can potentially affect several of the input files). Any of these options can be turned off once selected by appending a hyphen (-) to the option letter. This enables any global binary options selected in the system $COBDIR/etc/cobopt file to be overridden.

10.2.5.1 Command Line Examples

These examples show several uses of the cob command to compile, code generate and link programs.

For details on how to execute the files produced using the cob command, see the chapter Running. See also the chapters Creating Programs, Callable Shared Objects and Linking to System Executables for additional details.

10.2.6 Interface to Compiler

The cob command is used to interface to the COBOL compilation system. Compiler directives can be specified in a variety of ways, including via cob and via the program source files. The following sections describe all the ways that Compiler directives can be specified.

10.2.6.1 Program Source Conventions

The Server Express COBOL Compiler accepts source from a standard UNIX text file (as created by a UNIX editor such as vi). The format of this is the same as for standard COBOL, described in your Language Reference.

Each line of your COBOL source programs, including the last line, must be terminated by a new line character.

Your COBOL source programs must not contain any control characters (characters with hexadecimal values x"00" to x"1F" inclusive, or x"7F") except the tab character, unless they are embedded in literal strings. Tab is expanded with spaces to the next character position that is a multiple of eight.

10.2.6.2 Specifying Compiler Directives

You can specify Compiler directives in a number of ways, and the method used determines the order in which the Compiler processes them. The Compiler processes directives from left to right for each method of specifying them. If a directive appears more than once, the Compiler uses the setting that it processed last for that directive. The Compiler searches for directives in the following sequence of locations:

  1. COBOL system default directives in the file cobol.dir

  2. System default directives contained in cob options in the file $COBDIR/etc/cobopt

  3. User default directives contained in cob options in the environment variable COBOPT

  4. Compile-time directives contained in cob options on the cob command line

  5. Program-specific directives in the initial $SET statements in the source code file of each program

These methods are listed in the order in which the Compiler processes directives for each COBOL source file. This order of precedence means that a directive set on the command line would override another setting for that directive set in cobol.dir. For example, specifying the NOANS85 Compiler directive on the command line overrides ANS85 in cobol.dir.

You can further customize the Compiler's behavior by creating your own directives file; that is, an ASCII text file in which is defined an entire set of directives to be passed to the Compiler at one time. You can use either the DIRECTIVES or USE directive to pass this user directives file to the Compiler. You can determine the precedence for processing your directives file by specifying the DIRECTIVES or USE directive by any of the methods described above. See the section The DIRECTIVES and USE Directives later in the chapter.

Parameters to directives given in a $SET statement are converted to upper case; parameters to directives given on the cob command line or in a directives file retain their case.

The methods of specifying cob options and of specifying Compiler directives in cob options are given earlier in the section Invoking the cob Command. The additional methods of specifying Compiler directives are described in the following sections.

10.2.6.2.1 The cobol.dir Directives File

cobol.dir is a directives file that is processed automatically by the Compiler, as if the directive:

directives"cobol.dir"

were encountered by the Compiler as the very first directive after start-up. Consequently, Compiler directives contained in cobol.dir override the defaults built into the Compiler but can be overridden in turn by directives specified in the ways listed above. Generate phase directives cannot be specified in the cobol.dir directives file.

The Compiler looks for a cobol.dir file first in the current directory. If it finds one there, it uses it. Otherwise, it looks in the COBOL system directory $COBDIR.

If the Compiler rejects a directive contained in the cobol.dir file, compilation continues. However, if the Compiler rejects directives from either the command line or a directives file specified on the command line, compilation terminates. Therefore, if you create or change a cobol.dir file, you should do a trial compilation and watch for "rejected" messages at the beginning when the directives are being processed. If any occur, correct the cobol.dir file and retry until no errors are reported.

10.2.6.2.2 The $SET Statement

Many Compiler directives can be specified in the program source code in $SET statements. Compiler directives specified in this way supplement or override options specified in $COBDIR/etc/cobopt or in COBOPT. Generate phase directives cannot be specified using $SET statements.

You specify the $SET statement in the following format with the $ character in column 7:

$SET directive["parameter"] ... 

where the parameters are:

directive One of the Compiler directives described in the chapter Directives for Compiler whose phase is identified as "syntax check". It cannot be a generate phase directive (that is, one whose phase is identified as "generate").
parameter A qualifier to directive. It must appear in one of the following forms:

"parameter"

or

(parameter)

You cannot precede a parameter with an equals sign (=) in a $SET statement. parameter can contain spaces if enclosed in quotation marks (""), but not if enclosed in parentheses ( ).

... Indicates that further Compiler directives can be specified following the same format.

The $ character must be in column 7; if it is not, the Compiler does not recognize it and can produce spurious errors. The same is true for any character at the start of a source file that the Compiler does not recognize. Additionally, the $SET statement must not be terminated with a period (.).

If more than one directive is specified they must be separated by spaces. A $SET statement cannot be continued onto a new line, but it can be followed by additional $SET statements.

You can specify any number of $SET statements in your source code, and these can appear anywhere in the code. If you want to specify a dialect-controlling Compiler option, for example ANS85, this must be on an initial $SET statement; that is, one that is not preceded in the source file by any source statements except other $SET statements. Once you have set a dialect-controlling option at the beginning of your source code, you cannot unset it later in the program. When a directive is specified on a $SET other than an initial $SET, it affects compilation from the point the $SET is encountered onwards.

The chapter Directives for Compiler indicates which Compiler directives are allowed on $SET statements, distinguishing those only allowed on initial $SET statements.

Examples:

Both of the following examples have the same effect: they cause the Compiler to assume all file assignments to data names are resolved externally and to flag features in your program that are not in the ANSI'85 dialect of the COBOL language:

$SET assign(external) flag(ans85)
$SET assign "external" flag"ans85"
10.2.6.2.3 The DIRECTIVES and USE Directives

The DIRECTIVES and USE Compiler directives enable you to pass to the Compiler a user file containing a predefined set of directives. You can specify the DIRECTIVES or USE directive on the command line, in a $SET statement, in the cobol.dir file or in the $COBDIR/etc/cobopt file. Generate phase directives cannot be specified using DIRECTIVES or USE directives. The format for these directives is:

directives "filename"

or:

use "filename"

where filename is the name of the user file containing the set of directives you want to pass to the Compiler. It can be any valid filename except cobol.dir or $COBDIR/etc/cobopt.

A directives file is a standard ASCII text file containing any number of lines. Each line can contain one or more directives or comments. Directives in the directives file must be separated by a space and cannot be broken across two lines. Comment lines are indicated by an ampersand character (&) in column 1.

The Compiler reads the directives from the file until the end of file (EOF) is reached or another DIRECTIVES or USE Compiler directive is encountered.

If you specify the DIRECTIVES directive in another directives file, the Compiler switches to the new directives file for processing and then returns to the original directives file. When the Compiler completes processing the directives file, it then processes subsequent directives on the command line or in $SET statements.

Directives in a directives file are processed as if they were coded in place of the DIRECTIVES directive. Consequently, restrictions applying to any directive at that time also apply to all the directives in a directives file read at that time. See also the chapter Directives for Compiler.


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

PreviousLinking to System Executables Descriptions of cob FlagsNext