|Creating Programs||Directives for Compiler|
As you saw in the chapter Creating Programs, the Server Express Compiler compiles a program in two phases:
You use the Cob utility 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 a callable shared object, shared library or system executable file.
Callable shared object files, .int files and .gnt files are executable files that can be run without linking into a system executable file.
Executable file types are described in detail in the chapter Packaging Applications. The process by which you create the different executable file types was discussed in the chapter Creating Programs.
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 utility. The operation of the Cob utility is controlled by the cob command for which you can specify various flags. The cob command is described in the chapte. COBOL System Interface (Cob). The cob flags are described in the chapter Descriptions of cob Flags. If you are working in 64-bit mode, you should also see the chapter Working in 32-bit and 64-bit Modes.
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 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 the syntax-check or generate phase proceeds without displaying any messages unless an error is found.
If you specify the verbose option, each flag is acknowledged by the Compiler on a separate line and is either accepted, rejected or ignored. Those flags that are ignored are those that are not applicable to your environment, or to the syntax-check or generate phase. After all the flags have been acknowledged, the Compiler opens its files and starts the compilation process.
While syntax-checking 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 the cob command, 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 system 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 check.vnn. 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
program-id.idy). For example, if you compile the
source file file1 that contains two programs
ab is output to file1.int while
bc is output to bc.int.
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 Server Express VX.x revision xxx 15-Apr-99 16.49 Page 1 * filename Options: list-of-directives 1 Statement 1 : : n Statement n * Micro Focus Server Express revision
xxxCompiler * Copyright (C) 1984-2000 MERANT Intl URN
xxx-nnnnnnnnnxx* 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 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 cannot 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 off (-E) - which 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 cannot 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 and pipe facilities. 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 | tee compout.log
to create the redirection file containing the output from myprog, and then:
cob subprog.cbl -C ans85 | tee -a 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 are 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 stop 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:
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.
You can specify that generated files can be debugged by setting the -C anim or -g options on the command line. This creates the information files required by Animator.
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 pathname
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 pathname 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. MERANT recommends that you provide the name of the copyfile as a literal, in lower case, with the extension .cpy, and with no path.
A COPY statement must identify a file that contains the text to be copied; if the file is not available the Compiler either displays an error message 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 directive COPYEXT. The default values for this directive differ between products for the UNIX operating system and products for other environments. However, the default values can be readily changed by setting the COPYEXT directive. 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 5.1 of examples assume the UNIX default values for 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 effect for qualified COPY filenames.
COBCPY has the format:
where pathname 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 5-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 Filenames in your File Handling book. Additional searches for the required copyfile are made according to the mapping in such a dd_ variable.
This section shows you the best way to use the Compiler to keep your compilation time down.
If you are creating a large application, you can cut down the amount of time taken to compile a program by compiling using .int files. If you compile using the intermediate code file instead of the source file the Compiler will omit the check phase and go straight to the generate phase. For example, to compile myprog.int to a callable shared object you would need to type:
cob -z myprog.int
This would create the callable shared object myprog.so.
To create a system executable file from an .int file you would type:
cob -x myprog.int
There are several Compiler directives that affect the speed of a compilation. They are:
These directives are described briefly below. For more information on all directives, see the chapter Directives for Compiler.
The ALTER directive enables the use of ALTER statements in your
program. If you know there are no ALTER statements in your source code,
specifying NOALTER enables the Compiler to produce slightly more
efficient code and produce it more quickly. The Compiler assumes ALTER
as the default.
COPYLIST tells the Compiler to list the contents of all copyfiles
and include files. If you are creating a listing file, specifying
NOCOPYLIST results in faster compilation time, as COBOL copyfiles are
not expanded in the listing. The Compiler assumes COPYLIST as the
LIST specifies that you want a listing file to be created. If you
do not need to create a listing file, specifying NOLIST (the default)
speeds up the compilation process.
QUAL is required if you are using
qualified data-names; for example:
elementary-item-a of group-item-1
or if you are using typedefs of group items. The Compiler assumes
QUAL as the default.
If your program uses qualified data-names, but not qualified
paragraph-names, compilation can be accelerated by specifying
NOQUALPROC. The Compiler assumes QUALPROC as the default.
|SEG||The SEG directive enables the use of segments in your program. If you know there are no segments in your source code, specifying NOSEG enables the Compiler to produce slightly more efficient code and produce it more quickly. The Compiler assumes SEG as the default.|
If you always compile a program with a particular directive set you could use the $SET command in your program code to set the directive. For example, if your program does not use ALTER statements, you could set the directive in your program:
See the section Directives for more information on setting directives.
Copyright © 2000 MERANT International Limited. All rights reserved.
This document and the proprietary marks and names used herein are protected by international law.
|Creating Programs||Directives for Compiler|