HP 3000 Manuals HP 3000 Manuals
Operation
The command cob 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 cob
are identified by their extensions as follows:
Table 2-1. :cob File Types
-----------------------------------------------------------------------
| | |
| 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 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 2-1 . To do so, you must specify the -k cob flag to identify
them to cob (see Appendix D , 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 flags
listed in the section "cob Flags" . 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
Once invoked, the cob command first reads the startup file
$COBDIR/cobopt, which contains the system default options in the
following format:
set name=value
cob-option [cob-option]...
cobextn: .ext
A line must begin with one of the following recognized identifiers to be
processed.
* set, which enables environment variables to be assigned values.
* cob-option (for example, cob flag -a), in which case the line is
processed as part of the command line, or
* cobextn: .ext, which enables non-standard COBOL source file
extensions to be use.
Any line which does not begin with a recognized identifier is treated as
a comment.
The contents of $COBDIR/cobopt affect the operation of COBOL on the whole
system; it should be altered only after due consideration of the
implications.
cob next reads the environment variable COBOPT.
COBOPT either can contain further options (which can supplement or
override those specified in $COBDIR/cobopt), or it can be used to specify
the path of a file containing further options. In either instance, it
must follow the same format as that shown for the $COBDIR/cobopt file.
Finally, the options passed to the cob command on the command line are
processed. The options specified here can supplement or override those
already specified in $COBDIR/cobopt and COBOPT).
All options can use the syntax "option=param" rather than
"option(param)". cob will map any syntax using the equals sign (=) onto
the "option(param)" syntax acceptable to the COBOL components. To pass
the equals sign (=) to the COBOL components, you should use two equals
signs (==).
The COBOL compiler also can be passed options directly from embedded $SET
statements in the COBOL source code or via the cobol.dir directives file.
These methods of specifying options to cob are described in the following
sections.
Specifying cob Options
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 will look for a cobol.dir file first in the current
directory. If it finds one there, it will use it. Otherwise, it will
look in the COBOL system directory indicated by the environment variable
COBDIR.
If the compiler rejects a directive contained in the cobol.dir file,
compilation will continue. However, if the compiler rejects directives
from either the command line or a directives file specified on the
command line, compilation will terminate. 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 variables supported by the Micro
variable Focus COBOL System (see Appendix I , 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 flags listed in the section "cob Flags"
later in this chapter.
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 non-stantdard COBOL source file-name
extensions (that is, extensions other than .cbl,
.clb, 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.
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 environment variable COBOPT.
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- is any one of the variables supported by the Micro
variable Focus COBOL System (see Appendix I , 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 flags listed in the section "cob Flags"
later in this chapter. 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 non-stantdard COBOL source file-name
extensions (that is, extensions other than .cbl,
.clb, 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.
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.
For example:
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::
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 Appendix D , Descriptions
of cob Flags for details on -v).
cob Command Line Options
Command line options are specified on the cob command line as described
in the section "Invoking the cob Command" . You can specify any of
the options listed in the section "cob Flags" later in this chapter.
Compiler options are specified behind the -C flag and Generator options
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 Appendix G , Directives
for Compiler/Generator. 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.
For example:
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
Appendix G , Directives for Compiler/Generator.
It cannot be a Native Code Generator directive.
"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 G , Directives for Compiler/Generator indicates which
Compiler directives are allowed on $SET statements, distinguishing those
only allowed on initial $SET statements.
Example
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 create a user file containing a
predefined set of Compiler directives. This entire set of files can then
be passed to the compiler by specifying just one directive on the command
line, within a
$SET statement, 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 compiler
directives. It can be any valid file-name except for
$COBDIR/cobopt.
The 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 directives are read 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 processing of the
directives file is complete, subsequent directives on the command line or
in $SET statements will be processed.
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.
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 extensions
as shown in the table below:
Table 2-2. :cob File Processing
--------------------------------------------------------------------
| | | |
| Input File | cob Processing | Output |
| Type | | File Type |
| | | |
--------------------------------------------------------------------
| | | |
| .cbl | compile COBOL source code file into | .int |
| .CBL | intermediate code file | |
| .cob | | |
| | | |
--------------------------------------------------------------------
| | | |
| .int | code generate for dynamic loading | .gnt |
| | | |
--------------------------------------------------------------------
| | | |
| | code generate for static linking | .o |
| | | |
--------------------------------------------------------------------
| | | |
| .s | pass to system assembler | .o |
| | | |
--------------------------------------------------------------------
| | | |
| .c | pass C source text file to C compiler | .o |
| | | |
--------------------------------------------------------------------
| | | |
| .a | pass to system linker (ld) | a.out |
| .so | | |
| .o | | |
| | | |
--------------------------------------------------------------------
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 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 Chapter 6 , Linking.
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 use set the COBDIR
environment variable
to 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.
Files output by the cob command by default are placed in the current
directory. Any temporary files created are placed in the system
temporary directory by default; however, you can place them elsewhere by
setting the environment variable TMPDIR
and specifying a valid path name. See Appendix I , 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 Appendix D , Descriptions of cob Flags.
Table 2-3. :cob File Processing
-----------------------------------------------------------------------
| | |
| 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 |
| | |
-----------------------------------------------------------------------
-----------------------------------------------------------------------
| | |
| 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 flag
to 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.
Note that 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
Note that 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 -xe "" -o newrts
* To build a run time system that has linked in C routines, enter:
cob -xe "" -o newrts routines.c
For details on how to execute the files produced using the cob command,
see Chapter 7 Running. See also Chapter 3 Compiling Chapter 5
Generating and Chapter 6 Linking for additional details.