|Compiling Programs||Directives for Compiler|
The Object COBOL Compiler compiles a program in two phases:
You use the cob command to specify whether the Compiler is to perform its syntax-check or generate phase, or both phases.
Object code files contain no direct calls to the operating system, nor do they access the devices on your computer. Instead they contain calls to the run-time system, or to run-time support modules, that do the detailed work of calling the operating system to open and close files or to access the hardware devices on your computer. An object code file must be linked to create an executable file.
.int files and .gnt files are executable files that can be run without linking.
Executable file types are described in detail in the chapter Packaging Applications.
You can control the way your program is compiled by specifying Compiler directives. For example, you use a Compiler directive to specify that you want the Compiler to send a full listing to the screen as well as the printer.
Programs are compiled using the cob command. The operation of the cob command is controlled by various flags. The cob command is described in the chapter COBOL System Interface (cob). The cob flags are described in the chapter Descriptions of cob Flags. Compiler directives are specified on the cob command line.
Source code is usually held in files with the extension .cbl, .CBL or .cob.
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 compiling or generating. If you do not specify the verbose option, then compilation or generation proceeds without displaying any messages unless an error is found.
If you specify the verbose option, each option is acknowledged by the Compiler on a separate line and is either accepted, rejected or ignored. Those options that are ignored are those that are not applicable to your environment, or to the compile or generate phase. After all the options have been acknowledged, the Compiler opens its files and starts the compilation process.
While compiling or generating 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 the appendix Micro Focus Environment Variables for details on TMPDIR). The size of the 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 there is enough free space in the temporary area. Note that the most space is generally used while building executable files.
Temporary files are normally deleted by the Compiler before it
terminates. If the Compiler is interrupted or is terminated by machine
failure, it does not go through its clean-up routines; in this case, files
can be left on your disk. These files have names of the form
nn. You can delete them, if
cob is not running in any other session.
The Compiler, by default, compiles COBOL source code files into .int files, and also produces .idy files containing information for the Animator, unless some other end point is specified to the cob command.
If you compile a source file that contains multiple programs, the
resulting output file for the first program in that sequence is named source-file.int
(and source-file.idy); the output files for subsequent
programs in that source file is named program-id.int (and
For example, if you compile the source file
contains two programs
ab is output to
bc is output to
If the verbose option was specified, then when the syntax-check phase begins, the Compiler displays:
* Compiling filename
followed by other Compiler messages.
If the Compiler cannot open your source file, it issues the message:
Open fail : filename
The compilation is aborted and control is returned to UNIX. The most likely causes of errors at this time are:
If the Compiler finds syntax errors in your source code, it lists each line that contains an error, with an error message that briefly explains the problem. For further information on errors and error messages, see your Error Messages.
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.
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. The listing below illustrates the information contained in a full listing:
* Micro Focus COBOL for UNIX V
xxx15-Apr-96 16.49 Page 1 *
list-of-directives1 Statement 1 : :
n* Micro Focus COBOL for UNIX V
xxxCompiler * Copyright (c) 1984-1996 Micro Focus Ltd URN
xxx-nnnnnnnnnxn-xxxnnn* * Last message on page:
nn* * Total messages:
n* Data =
The first line of the listing displays the product name and version number and notes the date and time the listing was produced. The filename 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:
)--- ** description
where the variables are:
||The sequence number of the flagged line.|
||The coding that caused the flag to be raised.|
||The flag number.|
||Represents a language-level that does include the flagged syntax. For full details on the FLAG directive, see the chapter Directives for Compiler.|
||Indicates the page of the listing the previous flag occurred. This enables you to trace back from one flag to the previous one.|
||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.
If the Compiler detects an error in a data declaration, it can skip some subsequent data declarations, so 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 the variables are:
||The sequence number of the erroneous line.|
||The coding that caused the error|
||The Compiler error number.|
||A single alphabetic character representing the
category of the severity of the error:
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 below for further details.
||The page of the listing on which the previous error occurred. This enables you to trace back from one error to the previous one.|
||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 were issued, the Compiler displays the page-number of the listing on which the last message appeared, followed by the total number of messages, the number of messages in 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:
where the variables are:
||The size, in bytes, of the data division , including literals (if you have less than 64 Kilobytes of data)|
||The size of compiled intermediate code.|
Error messages issued by the Compiler 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 that the Compiler has tried to correct|
|Warning||Flags a statement that although is syntactically correct can 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 severity and the corresponding return values are shown in the following table:
|Informational||See INFORETURN directive|
U-level and S-level errors are always output by the Compiler. You can force the Compiler to output any of the remaining three levels of errors by setting the WARNING Compiler directive. See the chapter Directives for Compiler 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 that causes cob to stop processing. See the chapter 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 number of errors that occurred and the category these were in.
You can not run or generate intermediate code programs that contain any U-level errors. You first have to correct these errors and resubmit your source-code to the Compiler via the cob command.
You can run programs that contain S-level errors only if you set the E run-time switch on. See the chapter Descriptions of Run-time Switches for full details of how you can do this. If the E run-time switch is set off (-E), that is its default setting, trying to run intermediate code programs that contain S-level errors, gives a run-time error, and the program run terminates.
You can not produce generated or object code from intermediate code programs that contain S-level errors. Trying to do so results in a Compiler error in the generate phase.
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 that contain E-, W- and I-level errors, regardless of the setting of the E run-time switch.
A full list of Compiler error messages together with recovery hints can be found in your Error Messages.
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, myprog and subprog, into a single file, compout.log, enter:
cob myprog.cbl -C ans85 > compout.log
to create the redirection file containing the output from myprog, and then:
cob subprog.cbl -C ans85 >> compout.log
to append the output from subprog to the redirection file.
If you are compiling with the ERRQ directive, the prompts normally displayed by the Compiler is also redirected. Consequently, the Compiler appears to hang when really it is waiting for your response. If you think this is the case, use the interrupt key to terminate the compilation, and restart it without the ERRQ directive set.
After acknowledging all the cob options, the Compiler opens its files and starts the generate phase. At this point, if the verbose option is set, the Compiler displays the message:
* Generating filename
If the Compiler cannot open your source file, it issues the message:
* File open failure: filename
The generate phase is aborted and control is returned to UNIX. The most likely causes of errors are:
cob -u filename.cbl
then cob creates an .int, and then the .gnt file.
If no errors occur, then the system prompt reappears when the generating process is complete. If you set the -v cob flag, then the Compiler first provides statistics on data and code size.
When you generate native code for a segmented program, you specify on
the cob command line only the name of the root segment intermediate code
file. The compiler uses this name and automatically generates the
segments. The output files mirror the input files: a root generated code
file with extension .gnt and overlays with extensions .g
nn is in the range 50-99 corresponding to the
COBOL segment numbers. The exception to this is when a program is
generated for static linking. In this instance, all the overlays are
contained in the root file, that has the extension .o. On some
environments, a single .gnt file is produced for a segmented
program. On all environments, you can force a single .gnt to be
created by specifying the NOSEG directive (see the chapter Directives
for Compiler for details). This has no effect on the running of the
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 override these defaults as described in the section Setting Directives.
The following sections describe how you can specify directives. Descriptions of the individual directives are contained in the chapter Directives for Compiler.
Compiler directives are specified using a cob flag. Directives that affect the syntax-check phase are set using the -C cob flag . Directives that affect the generate phase are set using the -N cob flag .
The format for setting directives is:
where the parameters are:
||The cob command line flag used to specify directives. flag is C for syntax-check phase directives, N for generate phase directives.|
||One or more of the Compiler directives described in the chapter Directives for Compiler. If you do specify more than one directive, they must all be enclosed in quotation marks. This informs UNIX that all the directives in them are grouped together. If you omit the quotation marks, second and subsequent directives are ignored although no warning to this effect is given.|
||A qualifier to
and must adjoin
If you specify a Compiler option in a $SET statement or in a
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 (that has no special meaning to UNIX) to the format that 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.
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
cob -C "assign=external flag=ans85" pi.cbl
Both examples cause the Compiler to assume that 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. 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 in them are grouped behind the -C flag.
Directives can be entered in a number of ways. The order in which the various options are passed to the Compiler determines their precedence. See the chapter COBOL System Interface (cob) for details. Regardless of where they are specified, Compiler directives that affect the syntax-check phase always follow the -C cob flag, while those that affect the generate phase always follow the -N flag.
Full details on the directives available are contained in the chapter Directives for Compiler. Some of the directives are environment dependent and might not apply to your particular environment (any such restrictions are noted in the directive's description). The Compiler accepts them but treats them as documentary only.
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:
where the parameters are:
||Either a true COBOL user-defined word or a
COBOL user-defined word that also includes embedded non-COBOL
characters. It is not enclosed in quotation marks.
This COBOL system allows non-COBOL characters to be embedded in
|The name of a file, in quotation marks.
This COPY filename can have an extension and can incorporate a path-name
if there is no
||A COBOL user-defined word. It is not
enclosed in quotation marks.
|The name of a directory or library, in quotation marks. This COPY library-name can incorporate a path-name with any relative path being relative to the current directory. The name of the file can be folded to upper or lower case using the directive FOLDCOPYNAME.|
The COPY statement must be terminated with a period (.).
The Compiler treats a COPY library-name as the name of a directory, unless you use the COPYLBR directive. See the chapter Directives for Compiler for details.
If the optional phrases of the COPY statement are not specified, then the Compiler acts as if the directory containing the main source file had been specified as a library-name.
COBOL allows great flexibility in naming copyfiles. However, if you include any operating system dependent detail in the name then your COBOL source code might not readily compile if you move the source file to another operating system. Micro Focus recommends that you provide the name of the copyfile as a literal, in lower case, with the extension .cpy, and with no path. If you need to include a path, do not use the colon (:). You can retain the forward slash (/) in your pathnames, rather than use the backslash (\).
A COPY statement must identify a file that contains the text to be copied or the compiler either gives an error or prompts for the file interactively depending on the setting of the QUERY directive (see the chapter Directives for Compiler for details). The COPY statement can identify a specific file, by using a qualified COPY filename with an extension, otherwise it identifies an incomplete filename.
A filename can be incomplete either because it lacks a filename extension or because it lacks a filename path; in both cases the Compiler conducts a search as described below. The Compiler stops the search as soon as it finds a matching file and uses the contents of that file as the COPY text.
If the Compiler encounters a COPY filename that has an extension, then it only looks for files that have that extension. If the COPY filename has no extension, then, for any particular directory, the Compiler looks for files in that directory with extensions given by the directives OSEXT and COPYEXT. The default values for these directives differ between products for the UNIX operating system and products for other environments. However, the default values can be readily changed by setting the OSEXT and COPYEXT directives. See the chapter Directives for Compiler for details.
The Compiler searches, by default, for files with the following extensions in the sequence:
If the Compiler encounters a qualified COPY filename, then it only looks for the file in the directory specified in the COPY filename. If it encounters a simple COPY filename, then it looks for the file in the following directories in the sequence:
The references to .cbl in table 9.1 of examples assume the UNIX default values for OSEXT and COPYEXT and that the main source file is in the current directory.
The COBCPY environment variable directs the Compiler to look in additional directories for simple COPY filenames if they cannot be located in the given or default library. COBCPY has no affect for qualified COPY filenames.
The required format for values for COBCPY are shown in the following:
where path-name is a directory that the Compiler and Animator are to search when looking for copyfiles.
For example, if you specify the command line:
COBCPY="/usr/group/sharedcopy:.:/usr/mydir/mcpy" export COBCPY
the Compiler searches for a copyfile in /usr/group/sharedcopy, then in the current directory and finally in /usr/mydir/mcpy until either the copyfile is found or it can be considered not found.
Table 9-1 : Examples of Compiler Search Sequence
|COPY Statement||Contents of $COBCPY||Files Searched For (includes path)|
|COPY f1 OF dir1||dir1/f1
|COPY f1 IN dir1||/dir2||dir1/f1
Note: Before the system searches $COBCPY according to the rules given above, it searches for a dd_ environment variable in accordance with the rules given in the chapter File Naming in your Programmer's Guide to File Handling. Additional searches for the required copyfile are made according to the mapping in such a dd_ variable.
Copyright © 1999 MERANT International Limited. All rights reserved.
This document and the proprietary marks and names used herein are protected by international law.
|Compiling Programs||Directives for Compiler|