|Linking to System Executables||Descriptions of cob Flags|
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.
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.
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:
|.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).
To invoke the Cob utility, enter the following at the UNIX system prompt:
cob [options|filename] ...
where the parameters are:
||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.|
||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.|
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:
||The hyphen (-) or the plus (+) character|
||A letter (or occasionally letters) selected from those listed in the section cob Flags later in this chapter, that flags the required option.|
||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.
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:
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 "
or mode\(setting\) so enabling you to avoid these
characters. The cob command converts any syntax using the equals
sign (=) into the form
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.
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.
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:
||Any one of the environment variables supported by the COBOL system (see the appendix Micro Focus Environment Variables for details).|
||The value to which you want to set the specified environment variable.|
||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.|
||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
If a line does not begin with one of the identifiers
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.
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
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.
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).
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.
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.
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.
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|
|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|
|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.
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.
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.
|-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 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
|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.
These examples show several uses of the cob command to compile, code generate and link programs.
As this is the default case, the -a flag does not need to be specified.
cob -x pi.cbl
cob -i pi.cbl
This differs from the default case, shown in the first example, because an end point has been specified. In this case pi.int is not suitable for animation.
cob -u pi.cbl
cob -z pi.cbl
cob -xo newrts routines.c
cob -z myprog routines.c
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.
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.
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.
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:
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.
cobol.dir is a directives file that is processed automatically by the Compiler, as if the directive:
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.
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:
||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").|
||A qualifier to
You cannot precede a parameter with an equals sign (=) in a $SET
||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.
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"
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:
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.
|Linking to System Executables||Descriptions of cob Flags|