HP 3000 Manuals HP 3000 Manuals
Operation
The compiler is invoked using the -C flag
on the cob command line (see Chapter 2 , COBOL System Interface).
This section shows you how to specify directives to the compiler, either
when it is invoked or using a variety of other methods. The compiling
process and copy-file handling are also explained.
Directives
Directives are used to specify options that affect the way the compiler
behaves, what output it produces, what code is actually compiled and how
the compiled code behaves when run. All directives have a default built
into the compiler; however, you can create your own defaults as described
in the section "Setting Directives" .
The following sections describe how you can specify compiler directives.
Descriptions of the individual directives are contained in Appendix G
, Directives for Compiler/Generator.
Directives Syntax.
Use the following format to specify compiler directives:
-C [no]keyword"parameter"
where:
no turns keyword off. no must adjoin keyword. no
applies only to certain directives where specified
in their description in Appendix G , Directives
for Compiler/Generator.
keyword is one or more of the Compiler directives
described in Appendix G , Directives for
Compiler/Generator. If you do specify more than one
directive, they must all be enclosed within
quotation marks. This is necessary to inform UNIX
that all the directives within them are grouped
together. If you omit the quotation marks, second
and subsequent directives are ignored although no
warning to this effect is given.
"parameter" is a qualifier to keyword and applies
only to certain directives where specified in their
description in Appendix G , Directives for
Compiler/Generator. It must appear in one of the
following forms:
"parameter"
or
=parameter
or
(parameter)
and must adjoin keyword. You must not include any
spaces within a compiler option. This is because
UNIX treats the space character as an option
delimiter, so if you include any spaces within a
compiler option, UNIX regards the option as more
than one option. If parameter is file-name, then it
can be a fully specified file-name, including path,
unless otherwise stated.
If you specify a compiler option in a $SET statement
or in a DIRECTIVES file, parameter cannot be
preceded by an equals sign (=). It must be enclosed
either within double quotation marks (" ") or
parentheses.
We recommend that where possible you use the format of the option that
contains an equal sign before any parameter. cob maps the equals sign
(which has no special meaning to UNIX) to the format which uses
parentheses (as these do have a special meaning to UNIX). You are
recommended to use this format because if you use either of the other
possible formats, you must escape the quotation marks or parentheses with
the backslash character (\) whenever they might be misinterpreted by the
UNIX shell. As the equals sign has no special meaning, it does not need
to be escaped.
In this manual, parameters appear in quotation marks.
Examples
The following examples illustrate two ways to specify the same Compiler
directives using the equals sign before parameters as recommended:
cob -C assign=external -C flag=ans85 pi.cbl
or
cob -C "assign=external flag=ans85" pi.cbl
Both of these examples cause the Compiler to assume that 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. In the first example, the -C cob flag is specified
immediately before each Compiler directive. In the second, quotation
marks are used to inform UNIX that all the directives within them are
grouped behind the -C flag.
Setting Directives.
Directives, which are specified prior to compiling, can be entered in a
number of ways, and the order in which various options are passed to the
compiler determines their precedence. Regardless of the where they are
specified, Compiler directives always follow the -C cob flag. At
startup, the cob command processes options in the following sequence:
1. Directives from the system-wide directives file cobol.dir, which
is automatically processed every time you use the compiler.
2. Directives from the system-wide file $COBDIR/cobopt,
which is the first file processed when the compiler is invoked.
3. Directives from optional user defaults defined in the environment
variable COBOPT.
4. Directives behind the -C cob flag on the
cob command line.
5. Directives from initial
$SET statements in the program source code.
6. Directives from an optional user directives file created using
either the
DIRECTIVES or
USE directive, which is presented to the compiler for processing,
depending upon where the USE or DIRECTIVES directive is specified.
The setting of directives specified in any of these ways override their
default settings. Additionally, later directives override earlier ones.
So, for example, specifying NOANS85 on the command line will override
ANS85 in $COBDIR/cobopt. The DIRECTIVES and USE directives are processed
when they are encountered. There may be more than one of these
directives files.
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.
Some of the directives are environment dependent and may not be
applicable to your particular environment. The Compiler will accept them
but will treat them as documentary only. Your Release Notes list those
options which are not applicable to your environment.
For details on specifying options in any of these ways, see Chapter 2
, COBOL System Interface.
The Compiling Process
The Compiler, by default, compiles COBOL source code (.cbl, .cob or .CBL)
files into intermediate (.int) code files and produces .idy files
containing information for the Animator, unless some other end point was
specified to the cob command (see Chapter 2 COBOL System Interface.
If you compile a source file which contains multiple programs, the
resulting output file for the first program in that sequence will be
named source-file.int (or source-file.idy; the output files for
subsequent programs in that source file will be named PROGRAM- ID.int (or
PROGRAM-ID.idy). For example, if you compile the source file file1 which
contains two programs ab and bc, ab will be output to file1.int, while bc
will be output to BC.int To prevent Program-ID from being folded to upper
case, use the NOFOLDPROGID Compiler directive.
You can specify the verbose option (using the -v cob flag) on the cob
command line if you want to view any messages or errors issued during the
compiling process. See Appendix D , Descriptions of cob Flags for
details on the -v flag. If you do not specify the verbose option, then
the compiling process will proceed without displaying any messages unless
an error is found.
If you specify the verbose option, each compiler option is acknowledged
by the compiler on a separate line and is either accepted, rejected or
ignored. Those options which are ignored are those which are not
applicable to your environment. After all the options have been
acknowledged, the compiler opens its files and starts to compile. At
this point, it displays the message:
* Compiling file-name
While compiling your program, the compiler creates a number of temporary
work files in the directory indicated by the environment variable TMPDIR,
or in the directory /tmp or /usr/tmp if TMPDIR does not exist (see
Appendix I , Environment Variables for details on TMPDIR). The size of
these files depends on the end point specified to cob, the content of
your program and the directives used; in particular the number of data
and procedure names. Before starting the compilation, you should ensure
that there is enough free space in the temporary area and note that the
most space is generally used while building executable files.
These temporary files are normally deleted by the compiler before it
terminates. If the compiler is interrupted or is terminated by machine
failure, so that it does not go through its clean-up routines, then files
may be left on your disk. These files have names of the form
CHECK.Vnn. You can delete them, provided that cob is not running in any
other session.
If the compiler cannot open your source file, it issues the
message:
Open fail : file-name
The compilation is aborted and control is returned to UNIX. The most
likely causes of errors at this time are:
* you have not provided the correct file-name
* your source file extension is not .cbl, .CBL or .cob, and you have
not used the -k cob flag to identify a non-standard file-name
extension. (See Appendix D , Descriptions of cob Flags for
details on -k.
* your file is not in the directory you have specified, or it is not
in the current directory if you did not specify a path-name.
* you do not have read permission for a source or copy file or write
permission for the .int or .idy file, or the files are in use by
another process.
If the compiler finds syntax errors in your source code, it lists each
line that contains an error, along with the
error message that briefly explains the problem. For further information
on errors and error messages, see the Error Messages manual.
If your source code contains no syntax errors, then the system prompt
reappears when compilation is complete. If you set the -v cob flag, then
the compiler first provides statistics on data and code size.
Listing Format.
When the compiling process is complete, a listing file containing
information on the compiled program is displayed if the compilation
listing option (-P cob flag)
was set before compilation.
This format of the listing file below illustrates the information
contained in a full listing:
* Micro Focus COBOL for Unix V3.0 revision 001 15-Apr-92 16.49 Page 1
* file-name
Options: <list-of-directives>
1 Statement 1
:
:
n Statement n
* Micro Focus COBOL for UNIX V3.0 revision 001 Compiler
* Copyright (c) 1984,1992 Micro Focus Ltd URN xxxxx/xxn/nnnnnx
REF xxx-nnnnnnnnnxn-xxxnnn
* * Last message on page: nn
*
* Total messages: n
* Unrecoverable: n Severe: n
* Errors: n Warnings: n
* Informational: n Flags: n
* Data = nnnnnnnnn Code = nnnnnnnnn
This listing contains the following information:
The first line of the listing displays the product name and version
number and notes the date and time the listing was produced. The
file-name of the compiled program appears on the second line. If the
FLAG compiler directive was set, the second line also includes the
setting of this directive. These two lines appear at the top of each
page of the listing file. A list of the directives specified appears on
the next line.
If you specify the REF directive during compilation, a hexadecimal value
denoting the address of each data-name or procedure statement appears to
the right of the page. Addresses of data names are relative to the start
of the data area, while addresses of procedures (that is sections and
paragraphs) are relative to the start of the code area. There is some
overhead at the start of the data area, and some at the start of the
procedure area, including a few bytes of initialization code for each
SELECT statement.
The body of the listing displays your source code, providing details on
flags and syntax errors.
A flag is marked in the listing by a flagging line with the following
format:
nn flagged-feature
**--nnn--dialect--------------------(nnnn)---
** description
where:
nn is the sequence number of the flagged line.
flagged-feature is the coding that caused the flag to be raised.
nnn is the flag number.
dialect represents a language-level that does include the
flagged syntax. For full details on the FLAG
directive, see Appendix G , Directives for
Compiler/Generator.
nnnn indicates the page of the listing on which the
previous flag occurred. This enables you to trace
back from one flag to the previous one.
description indicates why the feature was flagged.
A program in which flags are indicated can still be run. Further details
can be found in your Error Messages manual.
If the compiler detects an error in a data declaration, it may skip some
subsequent data declarations, with the result that spurious error
messages are produced when references are made to data items whose
declarations have been skipped.
A syntax error is marked in the listing by an error line with the
following format:
nn illegal-statement
* nnn *A *** ******************* (nnnn**)
** description
where:
nn is the sequence number of the erroneous line.
illegal-statement is the coding that caused the error
nnn is the compiler error number.
A is a single alphabetic character representing the
category of the severity of the error:
U Unrecoverable
S Severe
E Error
W Warning
I Informational
In some circumstances, the compiler does not echo
the erroneous line to the terminal. Check the
previous line if there is any doubt. See the
section Compiler Error Messages for further details.
nnnn indicates the page of the listing on which the
previous error occurred. This enables you to trace
back from one error to the previous one.
description indicates why the syntax produced an error.
A summary appears at the end of the listing. The first line of the
listing summary repeats the product name and version number and the
component name. Copyright information, the user reference number and the
compiler reference number appear on the next two lines.
If any errors or messages have been given, then the listing page number
on which the last message appeared is displayed followed by the total
number of messages, the number of messages within each severity and the
total number of flags raised.
If no errors or messages were issued, then the following line appears
instead:
* Total Messages : 0
The last line provides information on the data and code size in the
following format:
Data=nnnnnnnnn Code=mmmmmmmmm
where:
nnnnnnnnn shows the size, in bytes, of the data division ,
including literals (if you have less than 64 Kilobytes
of data).
mmmmmmmmm shows the size of compiled intermediate code
Compiler Error Messages.
Error messages the compiler issues are classed according to their
severity, as follows:
Unrecoverable Indicates a fatal error
Severe Indicates an error that the compiler was unable to
correct. Compilation continues, but the statement
at fault is not compiled
Error Indicates an error which the compiler has attempted
to correct
Warning Flags a statement that although is syntactically
correct may contain a possible error
Informational Draws your attention to something in your source
code you should be aware of
The compiler returns a value to the operating system to show the most
severe type of message it issued. The possible severities and the
corresponding return values are shown in the following table:
Severity Return Value
Unrecoverable 16
Severe 12
Error 8
Warning 4
Informational See INFORETURN directive
No messages 0
U-level and S-level errors are always output by the compiler. You can
force the compiler to output any or all of the remaining three levels of
errors by setting the WARNING compiler directive. See Appendix G ,
Directives for Compiler/Generator for details. An unrecoverable error
always causes the compiler to stop, outputting the relevant error message
as it does so. By default, a severe error causes processing of the cob
command to stop after an intermediate code file has been produced, but
you can override this by using the -W flag on the cob command line. This
flag controls the error-level which causes cob to stop processing. See
Appendix G , Descriptions of cob Flags for full details on this flag.
If any S-, E-, W- or I-level errors are output by the compiler, a message
given at the end of its run indicates both the total number of errors
which occurred and which category these were in.
You will not be able to run or code generate intermediate code programs
which contain any U-level errors. You first will have to correct these
errors and resubmit your source-code to the compiler via the cob command.
You can run programs which contain S-level errors only if you set the E
run-time switch on. See Appendix E , Descriptions of Run-Time
Switches for full details of how you may do this. If the E run-time
switch is set off (-E), which is its default setting, attempting to run
intermediate code programs which contain S-level errors, will give a
run-time error, and the program run will terminate.
You will not be able to produce object code from intermediate code
programs which contain S-level errors. Attempting to do so will result
in a Native Code Generator error.
You can animate programs with S-level errors regardless of the setting of
the E run-time switch. If you animate such a program with the -E switch
setting, a run-time error is reported, but animation does not terminate.
You can animate, run and produce object files, from intermediate code
files which contain E-, W- and I-level errors, regardless of the setting
of the E run-time switch. However, you may wish to correct these errors
first.
A full list of compiler error messages together with recovery hints can
be found in your Error Messages manual.
Redirection of Compiler Output
All output from the compiler to the screen can be
redirected to a file by use of the standard UNIX redirection facilities
(> and >>). For example, to put all the compiler output from two
successive compilations into a single file, compout.log, enter:
cob myprog.cbl -C ans85 > compout.log
cob subprog.cbl -C ans85 >> compout.log
If you are compiling with the ERRQ directive, the prompts normally
displayed by the compiler will also be redirected. Consequently, the
compiler will appear to hang when really it is waiting for your response.
If you think this is the case, use the interrupt key to the compilation,
and restart it without the ERRQ directive set.
COPY Libraries
The COBOL
COPY statement, described in the Language Reference, can be used to
include COBOL source code from files other than the source code file
being compiled. This section defines how the names used in the COPY
statement relate to the physical files containing the source code to be
included.
The
basic COPY statement has the following format:
COPY {text-name } {OF} {library-name }.
{external-file-name-literal} {IN} {library-name-literal}
where:
text-name is the name of the file comprising the text to
be copied. It is not enclosed in quotation
marks and cannot include a path-name.
If a file-name with an extension is supplied,
then this is the only file searched for by the
compiler.
If no extension is supplied, then the compiler
will search the current directory for the
following files until one is found:
- the file-name with the extension specified
by the
OSEXT directive. By default, this is the
extension .cbl, but you can change it to
another by setting the OSEXT directive.
- the file-name with an extension of
.cpy
- the file-name with no extension.
text-name is always mapped to upper case.
external-file-name-literal
is the name of a file, in quotation marks.
This file-name can have an extension and can
incorporate a path-name if there is no
library-name or library-name-literal.
library-name identifies the location of the
copy-file identified by text-name or
external-file-name-literal. It must be the
name of a directory within the current
directory. library-name is always mapped to
upper case.
If no library name is given and the file-name
does not contain a path, the compiler looks in
the directory containing the main source file.
library-name-literal identifies the location of the
copy-file identified by text- name or
external-file-name-literal. It is a path name,
in quotation marks.
The COPY statement must be terminated with a period (.).
Copy Path-name.
The compiler can be directed to look in additional directories for the
text-name or external-file-name-literal if one of these cannot be found
in the specified location (library-name, library-name-literal or a
path-name incorporated in the file-name). You can set the environment
variable
COBCPY to a list of path-names identifying the additional directories.
For example, if you set COBCPY as follows:
COBCPY="/usr/group/sharedcopy:/usr/mydir/mcpy"
the compiler will search the directories in the order specified until the
copy-file is found. See Appendix I , Environment Variables for
details on setting COBCPY.
Search Sequence.
The following examples assume that the main source file is in the current
directory. See also the COPYEXT directive, which allows more flexibility
in the search order.Each file-name is tried in turn until one is located.
-------------------------------------------------------------------------
| | | |
| COPY Statement | Contents of $COBCPY | Files Searched For |
| | | Including Path |
| | | |
-------------------------------------------------------------------------
| | | |
| COPY f1 | | F1 |
| | | F1.cbl* |
| | | |
| COPY f1.cop | | F1.COP |
| | | |
| COPY f1.cop | dir1/ | F1.COP |
| | | dir1/F1.COP |
| | | |
| COPY "dir1/f1" | | dir1/f1 |
| | | dir1/f1.cbl* |
| | | |
| COPY f1 OF dir1 | | DIR1/F1 |
| | | DIR1/F1.cbl* |
| | | |
| COPY f1 | dir1/ | F1 |
| | | F1.cbl* |
| | | dir1/F1 |
| | | dir/F1.cbl* |
| | | |
-------------------------------------------------------------------------
* the file extension specified with the OSEXT compiler directive, by
default .cbl
Note: Before the system searches $COBCPY in accordance with the rules
given above, it searches for a dd_ environment variable in
accordance with the rules given in the section "File-Name
Mapping" in the chapter COBOL File Handling. Additional
searches for the required COPY file are made according to the
mapping in such a dd_ variable.