Compaq COBOL
User Manual

The cobol command can specify multiple file names and multiple flags. Multiple file names are delimited by spaces. If appropriate, each file name can have a different suffix. The file name suffix could result in the following actions:

• Calling another language compiler, such as the C compiler
• Passing object files directly to the linker, which the linker combines with other object files
• Passing an object library to the linker, which the linker uses to search for unresolved global references

When a file is not in your current working directory, specify the directory path before the file name.

1.1.2.5 Compiling Multiple Files

An entire set of source files can be compiled and linked together using a single cobol command:

% cobol -o calc mainprog.cob array_calc.cob calc_aver.cob

This cobol command:

• Uses the -o flag to specify the name of the executable program as calc
• Compiles the file array_calc.cob
• Compiles the file calc_aver.cob
• Compiles the file mainprog.cob , which contains the main program
• Uses ld to link both the main program and object files into an executable program file named calc

The files can also be compiled separately, as follows:

% cobol -c array_calc.cob % cobol -c calc_aver.cob % cobol -o calc mainprog.cob array_calc.o calc_aver.o

In this case, the -c option prevents linking and retains the .o files. The first command creates the file array_calc.o . The second command creates the file calc_aver.o . The last command compiles the main program and links the object files into the executable program named calc .

If your path definition includes the directory containing calc , you can run the program by simply typing its name:

% calc

You can compile multiple source files by concatenating them:

% cat proga1.cob proga2.cob proga3.cob > com1.cob % cat progb1.cob progb2.cob > com2.cob % cobol -c com1.cob com2.cob

The resulting file names are com1.o and com2.o. The OpenVMS Alpha equivalent to this is:

$ COBOL proga1+proga2+proga3,progb1+progb2

1.1.2.6 Debugging a Program

To debug a program using the Ladebug Debugger, compile the source files with the -g flag to request additional symbol table information for source line debugging in the object and executable program files. The following cobol command also uses the -o flag to name the executable program file calc_debug :

% cobol -g -o calc_debug mainprog.cob array_calc.cob calc_aver.cob

To debug an executable program named calc_debug, type the following command:

% ladebug calc_debug

For more information on running the program within the debugger, refer to the Ladebug Debugger Manual.

Pay attention to compiler messages. Informational and warning messages (as well as error-level messages) do not prevent the production of an object file, which you can link and execute. However, the messages sometimes point out otherwise undetected logic errors, and the structure of the program might not be what you intended.

1.1.2.7 Output Files: Object, Executable, Listing, and Temporary Files

The output produced by the cobol command includes:

• An object file, if you specify the -c flag on the command line
• An executable file, if you omit the -c flag
• A listing file, if you specify the -V flag

If the environment variable TMPDIR is set, the value is used as the directory for temporary files.

You control the production of these files by specifying the appropriate flags on the cobol command line. Unless you specify the -c flag, the compiler generates a single temporary object file, whether you specify one source file or multiple source files separated by blanks. The ld linker is then invoked to link the object file into one executable image file.

The object file is in Tru64 UNIX extended coff format. The object file provides the following information:

• The name of the entry point. It takes this name from the program name in the first PROGRAM-ID paragraph in the source program.
• A list of variables that are declared in the module. The linker uses this information when it binds two or more modules together and must resolve references to the same names in the modules.
• A symbol table and a source line correlation table (if you request them with the -g flag, for debugging). A symbol table is a list of the names of all external and internal variables within a module, with definitions of their locations. The source line correlation table associates lines in your source file with lines in your program. These tables are of use in debugging.

If severe errors are encountered during compilation or if you specify certain flags such as -c , linking does not occur.

1.1.2.8 Naming Output Files

To specify a file name (other than a.out ) for the executable image file, use the -o output flag, where output specifies the file name. You can also use the mv command to rename the file. The following command requests a file name of prog1.out for the source file test1.cob :

% cobol -o prog1.out test1.cob

Besides specifying the name of the executable image file, you can use the -o output flag to rename the object file if you specified the -c flag. If you specify the -c flag and omit the -o output flag, the name of the first specified file is used with a .o suffix substituted for the source file suffix.

1.1.2.9 Temporary Files

Temporary files created by the compiler or a preprocessor reside in the /tmp directory and are deleted (unless the -K flag is specified). You can set the environment variable TMPDIR to specify a directory to contain temporary files if /tmp is not acceptable.

To view the file name and directory where each temporary file is created, use the -v flag. To create object files in your current working directory, use the -c flag. Any object files ( .o files) that you specify on the cobol command line are retained.

1.1.2.10 Examples of the COBOL Command

The following examples show the use of the cobol command. Each command is followed by a description of the output files that it produces.

% cobol -V aaa.cob bbb.cob ccc.cob
      

The Compaq COBOL source files aaa.cob , bbb.cob , and ccc.cob are compiled into temporary object files. The temporary object files are passed to the ld linker. The ld linker produces the executable file a.out . The -V flag causes the compiler to create the listing files aaa.lis , bbb.lis , and ccc.lis .

% cobol -V *.cob
      

Compaq COBOL source files with file names that end with .cob are compiled into temporary object files, which are then passed to the ld linker. The ld linker produces the a.out file.

When the compilation completes, the cobol driver returns one of the following status values:

0---SUCCESS
1---FAILURE
2---SUBPROCESS_FAILURE ( cobol or cc )
3---SIGNAL

You can compile and link multilanguage programs using a single cobol command.

The cobol command recognizes C or Assembler program files by their file suffix characters and passes them to the cc compiler for compilation. Before compilation, cc applies the cpp preprocessor to files that it recognizes, such as any file with a .c suffix.

Certain flags passed to cc are passed to the ld linker.

1.1.2.12 Interpreting Messages from the Compiler

The Compaq COBOL compiler identifies syntax errors and violations of language rules in the program. If the compiler finds any errors, it writes messages to the stderr output file and any listing file. If you enter the cobol command interactively, the messages are displayed on your terminal.

Compiler messages have the following format:

cobol: severity: filename, line n, message-text [text-in-error] --------^

The pointer ( --^ ) indicates the exact place on the source line where the error was found. For example, the following error message shows the format and message text in a listing file when an END DO statement was omitted:

cobol: Severe: disp.cob, line 7: Missing period is assumed 05 VAR-1 PIC X. --------^

The severity level is one of the following:

Severe	The compiler does not produce an object module. You must correct the error before you can compile the program to produce an object module.
Error	The compiler makes an assumption about what you intended and continues. However, the compiler's assumption may not relate to your intention. Correct the error.
Warning	The compiler attempts to correct the error in the statement, but you should verify that the compiler's action is acceptable. Otherwise, your program may produce unexpected results.
Informational	This message usually appears with other messages to inform you of specific actions taken by the compiler. No action is necessary on your part.

Any messages issued during the compilation are inserted in the listing file. A listing file is useful for debugging the source code. Use the -V or -list flag to produce a listing; you may also use -cross_reference , -copy_list , -flagger , -machine_code , -map , and/or -warn , all of which affect the contents of the listing file.

Diagnostic messages provide information for you to determine the cause of an error and correct it. If the compiler creates a listing file, it writes the messages to the listing file.

1.1.3 Linking a Compaq COBOL Program on Tru64 UNIX

Once your program has compiled successfully, the system passes the resulting object file (which has the suffix .o by default) to the linker to create an executable image file. By default, the executable image file has the name a.out. (To change this default, specify -o filename on the cobol command line.) This file can be run on the Tru64 UNIX system.

The ld linker provides the following primary functions:

• Generates appropriate information in the executable image for virtual memory allocation
• Resolves symbolic references among object files being linked, including whether to search in archive or shared object libraries
• Assigns values to relocatable global symbols
• Performs relocation

The linker produces an executable program image with a default name of a.out.

When you enter a cobol command, the ld linker is invoked automatically unless a compilation error occurs or you specify the -c flag on the command line.

1.1.3.1 Specifying Object Libraries for Linking

You can specify object libraries on the COBOL command line by using certain flags or by providing the file name of the library. These object libraries are also searched by ld for unresolved external references.

When cobol specifies certain libraries to ld , it provides a standard list of COBOL library file names to ld . The ld linker tries to locate each of these library file names in a standard list of library directories. That is, ld attempts to locate each object library file name first in one directory, then in the second, and then in the third directory on its search list of directories.

To display a list of the compilers invoked, files processed, and libraries accessed during linking, specify the -v flag.

In addition to an object file created by the compiler, any linker flags and object files specified on the cobol command are also passed to the ld linker. The linker loads object files according to the order in which they are specified on the command line. Because of this, you must specify object libraries after all source and object files on the cobol command line.

To help identify undefined references to routines or other symbols in an object module, consider using the nm command. For instance, in the following example the nm command filtered by the grep command lists all undefined (U) symbols:

% cobol -c ex.cob % nm -o ex.o | grep U

If the symbol is undefined, U appears in the column before the symbol name. Any symbols with a U in their names can also be displayed by this use of grep .

1.1.3.2 Specifying Additional Object Libraries

You can control the libraries as follows:

• To specify additional object library file names for ld to locate, use the -l string flag to define an additional object library for ld to search. Thus, each occurrence of the -l string flag specifies an additional file name that is added to the list of object libraries for ld to locate. The standard COBOL library file names searched (shown in the form of the appropriate -l string flag) are:

  -lcob
  -lcurses
  -lFutil
  -lots2
  -lots
  -lisam
  -lsort
  -lexc
  -lm

  
  For instance, the file name of -lcob is libcob .
  The following example specifies the additional library libX :

  % cobol simtest.cob -lX

• In addition to the standard directories in which ld tries to locate the library file names, you can use the -L dir flag to specify another directory. The -l string flag and -L dir flag respectively adds an object library file name ( -l string) or directory path ( -L dir) that ld uses to locate all specified library files. The standard ld directories are searched before directories specified by the -L dir flag.
  The following example specifies the additional object library path /usr/lib/mytest :

  % cobol simtest.cob -L/usr/lib/mytest

• You can indicate that ld should not search its list of standard directories at all by specifying the -L flag. When you do so, you must specify all libraries on the cobol command line in some form, including the directory for cobol standard libraries. To specify all libraries, you might use the -L flag in combination with the -L dir flag on the same cobol command line.
• You can specify the pathname and file name of an object library as you would specify any file. Specifying each object library that resides in special directories in this manner is an alternative to specifying the library using the -l string or -L dir flag. This method can reduce the amount of searching the linker must do to locate all the needed object files.
  In certain cases, you may need to specify the pathname and file name instead of using the -l string or -L dir flags for the linker to resolve global symbols with shared libraries.

When processing a C source file ( .c suffix) using the cobol command, you may need to specify the appropriate C libraries using the -l string flag.

1.1.3.3 Specifying Types of Object Libraries

Certain cobol flags influence whether ld searches for an archive ( .a ) or shared object ( .so ) library on the standard list of COBOL libraries and any additional libraries specified using the -l string or -L dir flags. These flags are the following:

• The -call_shared flag, the default, indicates that .so files are searched before .a files. As ld attempts to resolve external symbols, it looks at the shared library first before the corresponding archive library. References to symbols found in a .so library are dynamically loaded into memory at run time. References to symbols found in .a libraries are loaded into the executable image file at link time. For instance, /usr/shlib/libc.so is searched before /usr/lib/libc.a .
• The -non_shared flag indicates that only .a files are searched, so the object module created contains static references to external routines and are loaded into the executable image at link time, not at run time. Corresponding .so files are not searched.
  The following example requests that the standard cobol .a files be searched instead of the corresponding .so files:

  % cobol -non_shared mainprog.cob rest.o

External references found in an archive library result in that routine being included in the resulting executable program file at link time.

External references found in a shared object library result in a special link to that library being included in the resulting executable program file, instead of the actual routine itself. When you run the program, this link gets resolved by either using the shared library in memory (if it already exists) or loading it into memory from disk.