Creating Programs

Directives for Compiler

Chapter 5: Using the Compiler

This chapter:

• Describes the Server Express Compiler
  
  
• Outlines the compilation process
  
  
• Explains how to use Compiler directives
  
  
• Describes the use of copyfiles in compilation

5.1 Introduction

As you saw in the chapter Creating Programs, the Server Express Compiler compiles a program in two phases:

• The first phase is the syntax-check phase. The Compiler checks the syntax of your COBOL source code for errors and creates an intermediate code file with the extension .int.
  
  
• The second phase is the generate phase. Depending on parameters you specify, the Compiler generates one of the following:
  
  
  • An .o file
    
    
  • A .gnt file

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 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.

5.2 Invoking the Compiler

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 cob -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 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 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.

5.3 Syntax-check Phase

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 and bc, 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:

• You have not provided the correct filename
  
  
• Your source file extension is not .cbl, .CBL or .cob, and you have not used the -k cob flag to identify a non-standard filename extension (see the chapter Descriptions of cob Flags for information on the -k cob flag).
  
  
• 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 copyfile 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, 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.

5.3.1 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. 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 xxx  Compiler
* Copyright (C) 1984-1999 Micro Focus Ltd   URN xxxxx/xxn/nnnnnx
                                            REF xxx-nnnnnnnnnxx
* Last message on page:  nn
*
* Total messages:   n
* Unrecoverable:    n   Severe:     n
* Errors:   n   Warnings:   n
* Informational:    n   Flags:      n
* Data = nnnnnnnnn   Code = nnnnnnnnn

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:

nn              flagged-feature
**--nnn--dialect--------------------(nnnn)---
**  description

where the variables are:

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:

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:

Data=nnnnnnnnn Code=mmmmmmmmm

where the variables are:

5.3.2 Compiler Error Messages

Error messages issued by the Compiler are classed according to their severity, as follows:

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:

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.

5.3.3 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 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 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.

5.4 The Generate Phase

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:

• You have not provided the correct filename
  
  
• You have not provided the file extension (the extension must be specified, even if it is .int). However, if you are processing .cbl files to generated files in one step then cob creates an .int, and then the .gnt file.
  
  
• Your file is not in the directory you have specified, it is not in the current directory if you did not specify a path-name, or you do not have the necessary access permission(s).

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.

5.5 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 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.

5.5.1 Directives Syntax

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:

-flag [no]keyword["parameter"]

where the parameters are:

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.

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 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.

5.5.2 Setting Directives

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.

5.6 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:

where the parameters are:

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.

Portability:
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.

5.6.1 Search Sequence

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 directive COPYEXT. The default values for this directive differs 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:

1. No extension
   
   
2. The extension .cbl
   
   
3. The extension .cpy

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:

1. The directory given by the COPY library-name or, if no library-name is given, in the directory containing the main source program being compiled.
   
   
2. Any directories that can be listed in the COBCPY environment variable.

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.

5.6.2 COBCPY Environment Variable

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.

COBCPY has the format:

COBCPY=path-name[:path-name]...

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 5-1 : Examples of Compiler Search Sequence

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.

5.7 Obtaining the Fastest Compilation Time

This section shows you the best way to use the Compiler to keep your compilation time down.

5.7.1 Compiling Using .int Files

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

5.7.2 Using Directives for Fast Compilation

There are several Compiler directives that affect the speed of a compilation. They are:

• ALTER
  
  
• COPYLIST
  
  
• LIST
  
  
• QUAL
  
  
• QUALPROC
  
  
• SEG

These directives are described briefly below. For more information on all directives, see the chapter Directives for Compiler.

elementary-item-a of group-item-1

If you will 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:

$SET noalter

See the section Directives for more information on setting directives.

Creating Programs

Directives for Compiler