HP 3000 Manuals HP 3000 Manuals
Operation
The cob command is used to interface to the COBOL compilation system. It
causes the named files to be processed with the aim of producing modules
which can be linked or run.
There are three basic types of runnable COBOL program, and the cob
command provides a straightforward means of creating a mixture of any of
these types of program:
* dynamically loadable, which is either a COBOL intermediate code
(.int) file or a COBOL generated code (.gnt) file
* dynamically linked, such as a standard UNIX system V release 4 ELF
executable object module which uses shared object (.so)
files(available only if your system supports dynamic linking)
* statically linked, such as a standard UNIX system executable
object module
The type of file output by cob is dependent upon the type of file you
input to it and the options you specify to the cob command. The file
types recognized by cobare identified by their extensions as follows:
-------------------------------------------------------------
| | |
| Extension | File Type |
| | |
-------------------------------------------------------------
| | |
| .cbl or .CBL or | COBOL source file |
| .cob | |
| | |
-------------------------------------------------------------
| | |
| .ini | 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 object module file |
| | |
-------------------------------------------------------------
| | |
| .o | object module file |
| | |
-------------------------------------------------------------
cob assumes that any unrecognized parameters are either valid linker
options or input files, so it saves them to be used at link time.
Similarly, 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 in
Table 7-1. To do so, you must specify the -k cob flag to identify them
to cob (see the appendix Descriptions of cob Flags for details) or use
the cobextn facility (described later in this chapter).
Invoking the cob Command
To invoke the cob command, enter the following at the UNIX system prompt:
cob [options|file-name]...
where:
options are one or more of the cob command line flagslisted in the
section cob Flags, or of the Compiler or Generator
directives listed in the appendix Directives for Compiler.
Options can be specified using any of the methods described
in the section Specifying cob Options.
file-name is the name of a source file to be input. 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), Assembler source (.s), or archive (.a)
files.
cob will reject any file-names which contain more than one
period (.). If you attempt to specify multiple periods
within a file-name, you will receive the following error:
cob: "." is not a valid character in file-name stem
Program Source Conventions
The Micro Focus 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, which is 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.
Specifying cob Options
cob options can be specified in a number of ways, and the method used to
specify options determines the precedence in which cob processes the
various options. At startup, the cob command processes options in the
following sequence:
1. Options from the system-wide directives file cobol.dir, which is
automatically processed every time you use the Compiler
2. Options from the system-wide directives file $COBDIR/cobopt, which
is the first file processed when the Compiler is invoked
3. Options from optional user defaults defined in the $COBOPT
environment variable.
4. Options specified on the cob command line
5. Options from initial $SET statements in the program source code
These methods are listed in the order in which cob processes options at
startup. 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.
Options to directives given in a $SET statement are converted to upper
case; options to directives given on the cob command line or in a
directives file are not.
These methods of specifying options to cob are described in the following
sections.
The cobol.dir Directives File.
cobol.dir is a directives file which is processed automatically by the
Compiler, just as if the directive:
directives"cobol.dir"
were specified before the source-file-name on every command line.
Consequently, Compiler directives contained in cobol.dir override the
defaults built into the Compiler. Generator 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 indicated by the COBDIR environment variable.
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.
The $COBDIR/cobopt File.
System-wide default options are defined in the file $COBDIR/cobopt. This
is the file the cob command reads first when invoked. Each line of this
file should correspond to one of the following formats:
[set environment-variable=value] [cob-options] [cobextn: .ext]
where:
environment- is any one of the environment variables supported by
variable the COBOL System (see the appendix Micro Focus
Environment Variables for details).
value is the value to which you wish to set the specified
environment variable.
cob-options is an optional sequence of one or more cob command
line options, including cob flags (see the section
cob Flags later in this chapter) and Compiler and
Generator directives (see the appendix Directives for
Compiler).
For options that take parameters, you can use the
syntax "option=param" or than "option(param)". cob
maps any syntax using the equals sign (=) onto the
"option(param)" syntax acceptable to the COBOL
components. To pass an actual equals sign (=) to the
COBOL components, you use two equals signs (==).
cob processes the command line from left to right.
If a directive appears more than once in the command
line, cob uses the setting of the directive it
processes last.
.ext is one or more nonstandard COBOL source file-name
extensions (that is, extensions other than .cob,
.cbl, or .CBL). The extension must begin with a
period, and if more than one is specified, they must
be space or tab separated. You may use more than one
cobextn line.
A line must begin with one of the recognized identifiers above (that is,
set, cob-option or cobextn:) to be processed. Any line which does not
begin with a recognized identifier is treated as a comment.
NOTE The contents of $COBDIR/cobopt affect the operation of COBOL on the
whole system; you should alter it only after due consideration of
the implications.
Examples.
Specifying the following cob options:
-N "nobound" -C "ans85"
passes the NOBOUND directive to the Native Code Generator and the ANS85
directive to the Compiler.
Assuming the following line in $COBDIR/cobopt:
cobextn: .AD .FD
specifying the cob command line:
cob -i a.FD b.AD
passes a.FD and b.FD to the Compiler to be translated into intermediate
(.int) code.
The COBOPT Environment Variable.
User default options are defined using the COBOPT environment variable.
COBOPT may either contain options which supplement or override the
system-wide default options defined in $COBDIR/cobopt, or it may specify
the path of a file which contains such options.
If you use COBOPT to point to a file which contains this type of option,
the format of the file must follow that of $COBDIR/cobopt (see the
section The $COBDIR/cobopt File).
If COBOPT contains the options itself, they take the form:
COBOPT="[set environment-variable=value]
[cob-options]
[cobextn: .ext]"
where:
environment-variable is as described in the section The
$COBDIR/cobopt File.
value is as described in the section The
$COBDIR/cobopt File.
cob-options is as described in the section The
$COBDIR/cobopt File.
.ext is as described in the section The
$COBDIR/cobopt File.
You must include the quotation marks, and COBOPT must not end in a space.
It is important that the set..., cob-options and cobextn statements
appear on different lines. Under the Bourne shell, Enter can be typed as
part of the COBOPT definition; however, under other environments, it may
be necessary to escape Enter or to indicate a line-break in some other
way.
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 appendix Descriptions of
cob Flags for details on -v).
Examples.
Specifying COBOPT as follows:
COBOPT='-C "noans85 nooptional-file" -N "nocheck lnkalign"'
passes the NOANS85 and NOOPTIONAL-FILE directives to the Compiler and the
NOCHECK and LNKALIGN directives to the Generator.
You can use the set statement in COBOPT to force the cob command to set
the specified environment variable to the specified value. For example:
set COBCPY=$COBDIR/srclib:$HOME/mylib:
cob Command Line Options.
Command line options are specified on the cob command line as described
in the section Invoking the cob Command. The options specified here can
supplement or override those already specified in $COBDIR/cobopt and
COBOPT. You can specify any cob flags, Compiler directives or Generator
directives. See the section cob Flags later in this chapter for a list
of available cob flags, and the appendix Descriptions of cob Flags for
full details of these flags.
Compiler directives are specified behind the -C flag and Generator
directives behind the -N flag on the cob command line. So the format for
specifying a Compiler directive on the cob command line is:
cob -C [directives] file-names
where:
directives is an optional sequence of one or more Compiler
directives described in the appendix Directives for
Compiler.
Each directive must be separated by a space and must
not be broken across two lines.
cob processes the command line from left to right.
If a directive appears more than once in the command
line, cob uses the setting of the directive it
processes last.
file-names are one or more files to which the directives apply.
Example.
Specifying the following on the cob command line:
cob -N lnkalign -C bell file1.cbl
passes the BELL directive to the Compiler and the LNKALIGN directive to
the Generator for file1.cbl.
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/cobopt or in COBOPT. Generator
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:
directive is one of the Compiler directives described in the
appendix Directives for Compiler whose phase is
identified as "syntax check". It cannot be a Native
Code Generator directive (that is, one whose phase is
identified as "generate").
"parameter" is 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 will not
recognize it and may produce spurious errors. The same is true for any
character at the start of a source file which the Compiler does not
recognize. Additionally, the $SET statement must not be terminated with
a period (.).
If more than one directive is specified, then 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 within 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 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 appendix 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 will be resolved
externally and to flag features in your program which 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 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, within a
$SET statement, in the cobol.dir file or in the $COBDIR/cobopt file.
Generator directives cannot be specified using DIRECTIVES or USE
directives. The format for these directives is:
directives "file-name"
or
use "file-name"
where file-name is the name of the user file containing the set of
directives you wish to pass to the Compiler. It can be any valid
file-name except for cobol.dir or $COBDIR/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 within 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 within 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 appendix Directives
for Compiler.
cob File Processing
In the process of creating an executable module, the cob command passes
each input file through a series of steps, each of which transforms one
file type into another file type. Thus, an output file from one step may
serve as an input file for a subsequent step. These types are
characterized by the file extensionsas shown in table 7-2 below:
Table 7-2: cob File Processing
------------------------------------------------------
| | | |
| Input | cob Processing | Output |
| File | | File |
| Type | | Type |
| | | |
------------------------------------------------------
| | | |
| .cbl | compile COBOL source code file | .int |
| .CBL | into intermediate code file | |
| .cob | | |
| | | |
------------------------------------------------------
| | | |
| .int | code generate for dynamic | .gnt |
| | loading | |
| | | |
------------------------------------------------------
| | | |
| | code generate for static linking | .o |
| | | |
------------------------------------------------------
| | | |
| .s | pass to system assembler | .o |
| | | |
------------------------------------------------------
| | | |
| .c | pass C source text file to C | .o |
| | Compiler | |
| | | |
------------------------------------------------------
| | | |
| .a | pass to system linker (ld) | a.out |
| .so | | |
| .o | | |
| | | |
------------------------------------------------------
By default, cob processing endswhen 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 already beyond the desired end point (for
example, when the desired end point is a dynamically loadable module and
an .o file is input for processing), cob assumes that the input files
have been specified because they are required and statically links them
with the dynamic loader. This produces an executable run time system,
which 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, which are left in the same directory as their input file.
A dynamically linked, statically linked or dynamically loadable COBOL
program, may access (using the COBOL CALL verb) any other statically
linked module within the same statically linked COBOL module or any other
dynamically loadable module. Assembler, C, or any other language modules
must conform to the C calling conventions and must be statically linked
into the COBOL executable. For details on creating these types of
modules, see the chapter Linking.
NOTE On file systems that support long file-names, you are recommended
to keep the length of program source file-names below the entry
point name limit. See the chapter Linking for further details.
Locating the COBOL System Components
In order to access the COBOL system components, the cob command must know
where they are located. By default, the components, together with any
configuration files, are placed in the directory specified during
installation, which is typically /usr/lib/cobol. If you place the Micro
Focus COBOL system software elsewhere, you must set the COBDIR
environment variableto tell cob in which directory to search for the
system components. For example:
COBDIR=/usr/cob32u1
export COBDIR
specifies that the system components are located in the directory
/usr/cob32u1.
By default, files output by the cob command are placed in the current
directory. By default, any temporary files created are placed in the
system temporary directory; however, you can place them elsewhere by
setting the TMPDIR environment variableand specifying a valid path name.
See the appendix Micro Focus Environment Variables for details on using
TMPDIR.
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 appendix Descriptions of cob Flags.
-------------------------------------------------------------
| | |
| cob Flag | Function |
| | |
-------------------------------------------------------------
| | |
| -A option | Pass option to assembler (as) |
| | |
-------------------------------------------------------------
| | |
| -a | Compile for animation. This is the |
| | default |
| | |
-------------------------------------------------------------
| | |
| -B mode[=option] | Select the system linker binding |
| | mode |
| | |
-------------------------------------------------------------
| | |
| +B mode[=option] | Select the system linker binding |
| | mode and pass to system linker after |
| | COBOL libraries |
| | |
-------------------------------------------------------------
| | |
| -C option | Pass option to COBOL Compiler |
| | |
-------------------------------------------------------------
| | |
| -CC option | Pass option to C compiler |
| | |
-------------------------------------------------------------
| | |
| -c | Compile no further than statically |
| | linkable object module (.o) |
| | |
-------------------------------------------------------------
| | |
| -d symb | Dynamically load symb |
| | |
-------------------------------------------------------------
| | |
| -e epsym | Set initial entry point |
| | |
-------------------------------------------------------------
| | |
| -F | Create an RTS quickly |
| | |
-------------------------------------------------------------
| | |
| +F symb | Create an RTS quickly and add symb |
| | to a linked data table |
| | |
-------------------------------------------------------------
| | |
| -f | Reserved for future use by Micro |
| | Focus |
| | |
-------------------------------------------------------------
| | |
| -g | Create information for symbolic |
| | debugger |
| | |
-------------------------------------------------------------
| | |
| -I symb | Include symb in executable file |
| | |
-------------------------------------------------------------
| | |
| -i | Compile to .int code for unlinked |
| | environment |
| | |
-------------------------------------------------------------
| | |
| -k cobol-file | Recognize COBOL source file with |
| | non-standard file-name extension |
| | |
-------------------------------------------------------------
| | |
| -L dir | Pass option to system linker,, |
| | changing search algorithm and |
| | maintaining relative ordering |
| | |
-------------------------------------------------------------
Table 7-0. (cont.)
-------------------------------------------------------------
| | |
| cob Flag | Function |
| | |
-------------------------------------------------------------
| | |
| +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 option | Pass option to Native Code Generator |
| | |
-------------------------------------------------------------
| | |
| -O | Enable optimization |
| | |
-------------------------------------------------------------
| | |
| -o file-name | Specify output file-name |
| | |
-------------------------------------------------------------
| | |
| -P | Produce COBOL compilation listing |
| | file |
| | |
-------------------------------------------------------------
| | |
| -p | Pass flag to C compiler to use |
| | profiling routines |
| | |
-------------------------------------------------------------
| | |
| -Q option or | Pass option to system linker (ld) |
| \-Q,1 option or | |
| \-Q,2 option | |
| | |
-------------------------------------------------------------
| | |
| -q | Reserved for future use by Micro |
| | Focus |
| | |
-------------------------------------------------------------
| | |
| -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 statically or dynamically |
| | linked executable module |
| | |
-------------------------------------------------------------
Any options which are not recognized are passed to the system linker
(ld). However, you are encouraged to use the -Q flagto explicitly pass
options to the linker. Any linker flags that take parameters must be
passed using the -Q flag.
cob flags -c, -F, -P and -U are binary global options (that is, they
select features which may potentially affect several of the input files).
Any of these options may be turned off once selected by appending a
hyphen (-) to the option letter. This allows any global binary options
selected in the system $COBDIR/cobopt file to be overridden.
Command Line Conventions.
You must observe the following conventions while specifying options (that
is Compiler directives, Native Code Generator directives or cob flags) on
the cob command line:
* options must start with a hyphen (-).
* options which have no arguments can be grouped behind one hyphen.
For example, command line flags -a and -P can be specified
together as follows:
cob -aP pi.cbl
to instruct cob to compile the COBOL source contained in pi.cbl
into a .int file that is suitable for animation and to produce a
listing file, pi.lst.
* options which do have arguments must have the first argument
preceded by at least one space.
* options followed by a group of arguments must have each parameter
separated by at least one space. The entire group must be
enclosed in quotation marks behind the single option, or the
option must be specified for each argument. For example:
cob -C "list noalter" pi.cbl
has the same effect as:
cob -C list -C noalter pi.cbl
Both pass the LIST and NOALTER directives to the Compiler.
Groups of arguments following an option and enclosed within
quotation marks must not exceed 128 characters.
* all options must precede operands. The end of the options may be
delimited by two hyphens (--).
* trailing hyphens may be used to switch off the options: -F, -c,
-P, -U. For example:
cob -x -c- pi.cbl
switches the -c option off so that it has no effect.
Command Line Examples.
These examples demonstrate several uses of the cob command to compile,
code generate and link programs.
* To compile the program in pi.cbl into a file called pi.int which
is suitable for animation, specify:
cob pi.cbl
As this is the default case, the -a flag does not need to be
specified.
* To compile, code generate and then link the COBOL source file
pi.cbl to the run-time support libraries to form a statically
linked a.out file named pi, enter:
cob -x pi.cbl
* To compile the COBOL source file pi.cbl for the unlinked
environment in order to produce an intermediate code file, pi.int,
enter:
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.
* To compile and code generate the program in pi.cbl into a
dynamically loadable native code file called pi.gnt, enter:
cob -u pi.cbl
* To compile, code generate and link the program contained in pi.cbl
to form a statically linked executable file named pi, enter:
cob -x -e "" pi.cbl
Specifying the -e flag with a null parameter (that is, " ")
ensures that the entry point is read from the command line at run
time. In effect, pi is linked to a full RTS as a callable
subprogram, so to invoke pi you would use the command:
pi pi
* To build just a run-time system than can dynamically run any .int
or .gnt files, enter:
cob -xo newrts
* To build a run-time system that has linked in C routines, enter:
cob -o newrts routines.c
* To build a run-time system that supports windowing syntax, enter:
cob -xI COBWIN1 -o newrts
See the appendix Windowing Support for full details on windowing
syntax.
For details on how to execute the files produced using the cob command,
see the chapter Running. See also the chapters Compiling, Generating and
Linking for additional details.