Compaq COBOL
User Manual

The COBOL command has the following format:

COBOL [/qualifier] ... {file-spec [/qualifier] ...} ...

/qualifier

Specifies an action to be performed by the compiler on all files or specific files listed. When a qualifier appears directly after the COBOL command, it affects all the files listed. By contrast, when a qualifier appears after a file specification, it affects only the file that immediately precedes it. However, when files are concatenated, these rules do not apply.

file-spec

Specifies an input source file that contains the program or module to be compiled. You are not required to specify a file type; the Compaq COBOL compiler assumes the default file type COB. If you do not provide a file specification with the COBOL command, the system prompts you for one.

You can include more than one file specification on the same command line by separating the file specifications with either a comma (,) or a plus sign (+). If you separate the file specifications with commas, you can control which source files are affected by each qualifier. In the following example, the Compaq COBOL compiler creates an object file for each source file but creates only a listing file for the source files entitled PROG_1 and PROG_3:

$ COBOL/LIST PROG_1, PROG_2/NOLIST, PROG_3

If you separate file specifications with plus signs, the Compaq COBOL compiler concatenates each of the specified source files and creates one object file and one listing file. In the following example, only one object file, PROG_1.OBJ, and one listing file, PROG_1.LIS, are created. Both of these files are named after the first source file in the list, but contain all three modules.

$ COBOL PROG_1 + PROG_2/LIST + PROG_3

Any qualifiers specified for a single file within a list of files separated with plus signs affect all files in the list.

1.2.2.3 Debugging a Program

To effectively debug a Compaq COBOL program, you must first make symbol and traceback information available by adding the DEBUG option to the compile command line. You specify the /DEBUG option as follows:

$ COBOL/DEBUG myprog $ LINK/DEBUG myprog $ RUN/DEBUG myprog

This enables you to examine and modify variables, monitor flow of control, and perform various other debugging techniques. See Section C.3 or type HELP COBOL/DEBUG or HELP DEBUG for additional information.

On Alpha, when you compile a program with /DEBUG, you should also specify /NOOPTIMIZE to expedite your debugging session. (The default is /OPTIMIZE.) Optimization often changes the order of execution of the object code generated for statements in a program, and it might keep values in registers and deallocate user variables. These effects can be confusing when you use the debugger. (A diagnostic message warns you if you compile a Compaq COBOL program with /DEBUG without specifying anything about optimization on the command line.)

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.2.2.4 Separately Compiled Programs (Alpha)

If a compilation unit consists of multiple separately compiled programs (SCPs), by default the Compaq COBOL compiler produces a single object file that consists of a single module with multiple embedded procedures. This object file can be inserted into an object library. If your build procedure requires that the linker extract any part of the module, the linker must extract the entire object.

If you use /SEPARATE_COMPILATION on the compile command line, Compaq COBOL will compile multiple SCPs into a single object file that consists of a concatenation of modules, each containing a single procedure. This object may then be inserted into an object library from which the linker can extract just the procedures that are specifically needed. <>

1.2.2.5 COBOL Qualifiers

COBOL options (also known as qualifiers or flags) control the way in which the compiler processes a file. You can process your file with the COBOL command alone or you can select options that offer you alternatives for developing, debugging, and documenting programs.

If you compile parts of your program (compilation units) using multiple COBOL commands, options that affect the execution of the program should be used consistently for all compilations, especially if data will be shared or passed between procedures.

Table 1-4 lists the COBOL command options and their defaults. For more information about COBOL options, invoke online help for COBOL at the system prompt.

Table 1-4 COBOL Command Qualifiers

The following are some common errors to avoid when entering COBOL command lines:

• Omitting /ANSI_FORMAT for programs that are in ANSI format (AREA A, AREA B, and so forth)
• Including contradictory options
• Omitting a necessary qualifier, such as /LIST if you specify /MAP
• Omitting version numbers from file specifications when you want to compile a program that is not the latest version of a source file
• Forgetting to use a file suffix in the file specification, or not specifying /SOURCE when your source file suffix is not .COB or .CBL

To debug source code that contains conditional compilation lines, you can use either the /CONDITIONALS qualifier or the WITH DEBUGGING MODE clause. The /CONDITIONALS qualifier is listed in Table 1-4. For more information about the /CONDITIONALS qualifier, invoke the online help facility for Compaq COBOL at the system prompt. For more information about the WITH DEBUGGING MODE clause, refer to the Compaq COBOL Reference Manual.

Using the WITH DEBUGGING MODE clause as part of the SOURCE-COMPUTER paragraph causes the compiler to process all conditional compilation lines in your program as COBOL text. If you do not specify the WITH DEBUGGING MODE clause, and if the /CONDITIONALS qualifier is not in effect, all conditional compilation lines in your program are treated as comments.

The WITH DEBUGGING MODE clause applies to: (1) the program that specifies it, and (2) any contained program within a program that specifies the clause.

1.2.2.8 Interpreting Messages from the Compiler

If there are errors in your source file when you compile your program, the Compaq COBOL compiler flags these errors and displays helpful messages. You can reference the message, locate the error, and, if necessary, correct the error in your program.

On Alpha, the general format of compiler messages shown on your screen is as follows:

..........................^
%COBOL-s-ident, message-text
At line number n in name <>

On VAX, the general format of compiler messages is as follows:

%COBOL-s-ERROR nnn, (m) message-text
<>

%COBOL

The facility or program name of the Compaq COBOL compiler. This prefix indicates that the Compaq COBOL compiler issued the message.

s

The severity of the error, represented in the following way:

F	Fatal error. The compiler does not produce an object module. You must correct the error before you can compile the program to produce an object module.
E	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.
W	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.
I	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. Note that these messages are suppressed by default. You must invoke /WARN=ALL or /WARN=INFO to enable them.

ident (Alpha)

The message identification. This is a descriptive abbreviation of the message text. <>

nnn (VAX)

The message identification number.

m (VAX)

The message pointer number. <>

message-text

The compiler's message. In many cases, it consists of no more than one line of output. A message generally provides you with enough information to determine the cause of the error so that you can correct it.

At line number n in name (Alpha)

The integer n is the number of the line where the diagnostic occurs. The number is relative to the beginning of the file or text library module specified by name.

On Alpha, a sample compiler message with two diagnostics looks like this in the listing file:

12 PROCEDURE DIVISION. 13 P-NAME 14 MOVE ABC TO XYZ. ................^ %COBOL-E-NODOT, Missing period is assumed 14 MOVE ABC TO XYZ. ............................^ %COBOL-F-UNDEFSYM, Undefined name

In the sample, the first diagnostic pointer (^) points to the MOVE statement in source line number 14, which is the closest approximation to where the error (P-NAME is not followed by a period) occurred. The second diagnostic pointer points to XYZ, an undefined name in source line number 14. Each diagnostic pointer is followed by a message line that identifies, in this order:

• The Compaq COBOL compiler generated the message
• The severity code of the message
• The message identification (a mnemonic of the message text)
• The text of the message

Although most compiler messages are self-explanatory, some require additional explanation. The online help facility for Compaq COBOL contains a list and descriptions of these Compaq COBOL compiler messages. Use the HELP COBOL Compiler Messages command to access this list. <>

On OpenVMS VAX, diagnostic messages look like this example:

12 PROCEDURE DIVISION. 13 P-NAME 14 MOVE ABC TO XYZ. 1 2 %COBOL-E-ERROR 65, (1) Missing period is assumed %COBOL-F-ERROR 349, (2) Undefined name

Here, error pointer (1) points to the approximate place where the error occurred (P-NAME has no period). Error pointer (2) points to an undefined name in source line number 14. The two error pointers are followed by two error message lines that each identify, in this order:

• That the COBOL compiler generated the error message
• The severity code: Fatal (F), Error (E), Warning (W), or Informational (I)
• The error message number
• The error pointers
• The error message <>

To examine messages that occurred during compilation, you can search for each occurrence of %COBOL in the compiler listing file. Section 1.2.2.9 describes listing files.

1.2.2.9 Using Compiler Listing Files

A compiler listing file provides information that can help you debug or document your Compaq COBOL program. It consists of the following sections:

• Program listing
  The program listing section contains the source code plus line numbers generated by the compiler. Any diagnostics will appear in this section.
• Storage map
  The storage map section is optional (produced by the /MAP qualifier); it contains summary information on program sections, variables, and arrays.
• Compilation summary
  The compilation summary section lists the qualifiers used with the COBOL command and the compilation statistics.
• Machine code
  The machine code section is optional; it displays compiler-generated object code.

To generate a listing file, specify the /LIST qualifier when you compile your Compaq COBOL program interactively as in the following example for PROG_1.COB:

$ COBOL/LIST PROG_1.COB

If you compile your program as a batch job, the compiler creates a listing file by default. You can specify the /NOLIST qualifier to suppress creation of the listing file, if that suits your purposes. (In either case, however, the listing file is not automatically printed.) By default, the name of the listing file is the name of your source file followed by the file type .LIS. You can include a file specification with the /LIST qualifier to override this default.

When used with the /LIST qualifier, the following COBOL command qualifiers supply additional information in the compiler listing file:

• /COPY_LIST---Includes source statements specified by the COPY command.
• /CROSS_REFERENCE---Creates a cross-reference listing of user-defined names and references.
• /MACHINE_CODE---Includes a list of compiler-generated machine code.
• /MAP---Produces maps, data names, procedure names, file names, and external references.

For a description of each qualifier's function, invoke the online help facility for COBOL at the system prompt as follows:

$ HELP COBOL

Compiler Listing File for a Contained Program

A contained COBOL program listing file includes two additional program elements that provide nesting level information about the main program and the contained program. For additional information about contained programs, see Chapter 12, Interprogram Communication.

1.2.3 Linking a Compaq COBOL Program

After you compile a Compaq COBOL source program or module, use the LINK command to combine your object modules into one executable image that the OpenVMS system can execute. A source program or module cannot run until it is linked.

When you execute the LINK command, the OpenVMS Linker performs the following functions:

• Resolves local and global symbolic references in the object code
• Assigns values to the global symbolic references
• Signals an error message for any unresolved symbolic reference
• Allocates virtual memory space for the executable image

The LINK command produces an executable image by default. However, you can specify qualifiers and qualifier options with the LINK command to obtain shareable images and system images.

See Table 1-5 for a list of commonly used LINK command qualifiers. For a complete list and for more information about the LINK qualifiers, invoke the online help facility for the LINK command at the system prompt.

For a complete discussion of linker capabilities and for detailed descriptions of LINK qualifiers and qualifier options, refer to the OpenVMS Linker Utility Manual.

1.2.3.1 The LINK Command

The format of the LINK command is as follows:

LINK[/qualifier] ... {file-spec[/qualifier] ...} ...

/qualifier...

Specifies output file options when it is positioned after the LINK command. Specifies input file options when it is positioned after file-spec.

file-spec...

Specifies the input files to be linked.

If you specify more than one input file, you must separate the input file specifications with a plus sign (+) or a comma (,).

By default, the linker creates an output file with the name of the first input file specified and the file type EXE. If you link multiple files, specify the file containing the main program first. Then the name of your output file will have the same name as your main program module.

The following command line links the object files MAINPROG.OBJ, SUBPROG1.OBJ, and SUBPROG2.OBJ to produce one executable image called MAINPROG.EXE:

$ LINK MAINPROG, SUBPROG1, SUBPROG2

1.2.3.2 LINK Qualifiers

LINK qualifiers allow you to control various aspects of the link operation such as modifying linker input and output and invoking the debugging and traceback facilities.

Table 1-5 summarizes some of the more commonly used LINK qualifiers. Refer to the OpenVMS Linker Utility Manual for a complete list and explanations of the LINK qualifiers or invoke the online help facility for the LINK command at the OpenVMS prompt.

Table 1-5 Commonly Used LINK Qualifiers

Function	Qualifier	Default
Indicate that an input file is a library file.	/LIBRARY	Not applicable.
Indicate that an input file is a linker options file.	/OPTIONS	Not applicable.
Request output file, define a file specification, and specify whether the image is shareable.	/EXECUTABLE[=file-spec] /SHAREABLE[=file-spec]	/EXECUTABLE=name.EXE where name is the name of the first input file. /NOSHAREABLE
Request and specify the contents of an image map (memory allocation) listing.	/BRIEF /[NO]CROSS_REFERENCE /FULL /MAP[=file-spec] or /NOMAP	/NOCROSS_REFERENCE /NOMAP (interactive) /MAP=name.MAP (batch) where name is the name of the first input file.
Specify the amount of debugging information.	/DEBUG[=file-spec] or /NODEBUG /[NO]TRACEBACK	/NODEBUG /TRACEBACK

1.2.3.3 Specifying Modules Other than Compaq COBOL Modules

When you link Compaq COBOL modules with other modules, your application will not work correctly if a non Compaq COBOL module contains a LIB$INITIALIZE routine that:

1. Is invoked before the Compaq COBOL LIB$INITIALIZE routine (COB_NAME_START) and
2. Calls a Compaq COBOL program that contains CALL by data name, extended ACCEPT, or extended DISPLAY statements.

Compaq COBOL uses the LIB$INITIALIZE routine, COB_NAME_START, to initialize the run-time environment for the CALL by data name and extended ACCEPT and DISPLAY statements. Therefore, the COB_NAME_START routine must be invoked before any CALL, ACCEPT, or DISPLAY statements are performed.

The order in which LIB$INITIALIZE routines are invoked is determined during the link and is shown in the image map. To ensure that the Compaq COBOL LIB$INITIALIZE routine is invoked first, change your link command to the following:

$ LINK/EXE=name SYS$SHARE:STARLET/INCL=COB_NAME_START,your_modules...

See Appendix B for information on a problem with LIB$INITIALIZE when you call a C program.

1.2.3.4 Specifying Object Module Libraries

Linking against object modules allows your program to access data and routines outside of your compilation units. You can create your own object module libraries or they can be supplied by the system.

User-Created Object Module Libraries

You can make program modules accessible to other programmers by storing them in object module libraries. To link modules contained in an object module library, use the /INCLUDE qualifier with the LINK command² and specify the modules you want to link. The following example links the subprogram modules EGGPLANT, TOMATO, BROCCOLI, and ONION (contained in the VEGETABLES library) with the main program module GARDEN:

$ LINK GARDEN, VEGETABLES/INCLUDE=(EGGPLANT,TOMATO,BROCCOLI,ONION)

An object module library also contains a symbol table with the names of the global symbols in the library, and the names of the modules in which the symbols are defined. You specify the name of the object module library containing these symbol definitions with the /LIBRARY qualifier. When you use the /LIBRARY qualifier during a linking operation, the linker searches the specified library for all unresolved references found in the included modules during compilation.

The following example uses the library RACQUETS to resolve undefined symbols in the BADMINTON, TENNIS, and RACQUETBALL libraries:

$ LINK BADMINTON, TENNIS, RACQUETBALL, RACQUETS/LIBRARY

For more information about the /INCLUDE and /LIBRARY qualifiers, invoke the online help facility for the LINK command at the DCL prompt or refer to the OpenVMS Linker Utility Manual.

You can define one or more of your private object module libraries as default user libraries. The following section describes how to accomplish this using the DEFINE command.

Defining Default User Object Module Libraries

You can define one or more of your private object module libraries as your default user libraries using the DCL DEFINE command, as in the following example:

$ DEFINE LNK$LIBRARY DEFLIB

The linker searches default user libraries for unresolved references after it searches modules and libraries specified in the LINK command.

In this example, LNK$LIBRARY is a logical name and DEFLIB is the name of an object module library (having the file type OLB) that you want the linker to search automatically in all subsequent link operations.

You can establish any object module library as a default user library by creating a logical name for the library. The logical names you must use are LNK$LIBRARY (as in the preceding example), LNK$LIBRARY_1, LNK$LIBRARY_2, and so on, to LNK$LIBRARY_999. When more than one of these logical names exists when a LINK command executes, the linker searches them in numeric order beginning with LNK$LIBRARY.

When one or more logical names exist for default user libraries, the linker uses the following search order to resolve references:

• The process, group, and system logical name tables (in that order) are searched for the name LNK$LIBRARY. If the logical name exists in any of these tables and if it contains the desired reference, the search is ended.
• The process, group, and system logical name tables (in that order) are searched for the name LNK$LIBRARY_1. If the logical name exists in any of these tables, and if it contains the desired reference, the search is ended.

This search sequence occurs for each reference that remains unresolved.

System-Supplied Object Module Libraries

All Compaq COBOL programs reference system-supplied object module libraries when they are linked. These libraries contain routines that provide I/O and other system functions. Additionally, you can use your own libraries to provide application-specific object modules.

To use the contents of an object module library, you must do the following:

• Refer to a symbol in the object module by name in your program in a CALL statement or VALUE EXTERNAL reference.
• Make sure that the linker can locate the library that contains the object module by ensuring that required software is correctly installed.
• Make sure that your default directory (or LINK/EXE directory) is valid and that you have write privileges to it.