After you compile a DEC C source program or module, use the DCL command LINK to combine your object modules into one executable image, which can then be executed by the OpenVMS system. A source program or module cannot run on the OpenVMS system until it is linked.
When you execute the LINK command, the linker performs the following functions:
When using the LINK command on development systems, use the /DEBUG qualifier to link your program module. The /DEBUG qualifier appends to the image all the symbol and line number information appended to the object modules plus information on global symbols, and causes the image to run under debugger control when it is executed.
The LINK command produces an executable image by default. However, you can also use the LINK command to obtain shareable images and system images. The /SHAREABLE qualifier directs the linker to produce a shareable image; the /SYSTEM qualifier directs the linker to produce a system image. See Section 1.4.2 for a complete description of these and other LINK command qualifiers.
For a complete discussion of the OpenVMS Linker, see the OpenVMS Linker Utility Manual.
The LINK command has the following format:
LINK[/command-qualifier]... {file-spec[/file-qualifier...]},...
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 more than one file, you should 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 execution of a program will begin at the function whose identifier is main, or, if there is no function with this identifier, at the first function seen by the VMS linker.
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.OBJ, SUBPROG1.OBJ, SUBPROG2.OBJ
You can use the LINK command qualifiers to modify the linker's output, as well as to invoke the debugging and traceback facilities. Linker output consists of an image file and an optional map file.
The following list summarizes some of the most commonly used LINK command qualifiers. A brief description of each qualifier follows this list. For a complete list of LINK qualifiers, see the OpenVMS Linker Utility Manual. Command Qualifiers Default /BRIEF None. /[NO]CROSS_REFERENCE /NOCROSS_REFERENCE /[NO]DEBUG /NODEBUG /[NO]EXECUTABLE[=file-spec/EXECUTABLE=name.EXE /FULL None. /[NO]MAP /MAP (batch) /NOMAP (interactive) /[NO]SHAREABLE[=file-spec]/NOSHAREABLE /[NO]TRACEBACK /TRACEBACK
You can specify the object modules to be included in an executable image in any of the following ways:
If no file type is specified, the linker searches for an object file with the file type OBJ.
You can specify either the name of an object module library with the /LIBRARY qualifier or the names of the object modules contained in an object module library with the /INCLUDE qualifier. Section 1.4.6 describes the uses of object module libraries.
An options file can contain additional file specifications for the LINK command, as well as special linker options. You must use the /OPTIONS qualifier to specify an options file. For more information on options files, see the OpenVMS Linker Utility Manual.
Table 1-22 shows the default input file types for the linker.
| File Type | File |
|---|---|
| OBJ | Object module |
| OLB | Library |
| OPT | Options file |
When you enter the LINK command interactively and do not specify any qualifiers, the linker creates only an executable image file. By default, the resulting image file has the same file name as that of the first object module specified with a file type of EXE.
In a batch job, the linker creates both an executable image file and storage map file by default. The default file type for map files is MAP.
To specify an alternative name for a map file or image file or to specify an alternative output directory or device, you can include a file specification on the /MAP or /EXECUTABLE qualifier. In the following example, the LINK command creates the image file [PROJECT.EXE]UPDATE.EXE and the map file [PROJECT.MAP]UPDATE.MAP:
$ LINK UPDATE/EXECUTABLE=[PROJECT.EXE]/MAP=[PROJECT.MAP]
Linking against object modules (stored in object module libraries) or against shareable images are ways of allowing your program to access data and routines outside of your compilation units. You can either create the object module libraries and the shareable images or use the ones provided by Digital. To access data in object modules and shareable images, you can use LINK command qualifiers, OpenVMS logical names, and options files. For more information about object module libraries, see the OpenVMS Linker Utility Manual.
The DEC C Run-Time Library (RTL) for OpenVMS systems also provides two formats for you to choose from: shareable images or object module libraries. Depending on which type of RTL you want to use and on which type of functions you plan on calling from your programs, you need to supply information to the linker that specifies which versions of the functions to access.
When you use the DEC C RTL and its corresponding header files, remember that the DEC C RTL ships with the OpenVMS operating system and the header files ship with the DEC C compiler. Since the releases of the compiler and of the operating system are not synchronized, there may be compatibility issues that you need to consider to use the RTL properly. See the DEC C release notes (by entering HELP CC /DECC RELEASE_NOTES on the DCL command line) for information that may pertain to this issue.
For a description of the various ways to link with the DEC C RTL, see the DEC C Run-Time Library Reference Manual for OpenVMS Systems.
You can make program modules accessible to other users by storing them in an object module library. To link modules contained in an object module library, use the /INCLUDE qualifier and specify the modules you want to link. The following example links the subprogram modules EGGPLANT, TOMATO, BROCCOLI, and ONION with the main program module GARDEN:
$ LINK GARDEN, VEGGIES/INCLUDE=(EGGPLANT,TOMATO,BROCCOLI,ONION)
An object module library can also contain a symbol table with the names of each global symbol in the library, and the name of the module in which they are defined. You specify the name of the object module library containing 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 BADMINTON, TENNIS, and RACQUETBALL:
$ LINK BADMINTON, TENNIS, RACQUETBALL, RACQUETS/LIBRARY
You can define an object module library to be your default library by using the DCL command DEFINE LNK$LIBRARY. The linker searches default user libraries for unresolved references after it searches modules and libraries specified in the LINK command. For more information about the DEFINE command, see the OpenVMS DCL Dictionary.
For more information about object module libraries, see the OpenVMS Linker Utility Manual.
If the linker detects any errors while linking object modules, it displays messages indicating the cause and severity of the error. If any error or fatal error conditions occur (that is, errors with severities of E or F), the linker does not produce an image file.
The messages produced by the linker are descriptive, and you do not usually need additional information to determine the specific error. Some common errors that occur during linking are as follows:
This occurs when you try to link a module that produced warning messages during compilation. You can usually link compiled modules for which the compiler generated messages, but verify that the modules will produce the output you expect.
If you do not specify a file type, the linker searches for a file that has a file type of OBJ by default. If the file is not an object file and you do not identify it with the appropriate file type, the linker signals an error message and does not produce an image file.
The linker signals an error message if you misspell a module name on the command line or if the compilation contains fatal diagnostics.
An error occurs when you omit required module or library names from the command line and the linker cannot locate the definition for a specified global symbol reference. Consider, for example, the following LINK command for a main program module, OCEAN.OBJ, that calls the subprogram modules REEF.OBJ, SHELLS.OBJ, and SEAWEED.OBJ:
$ LINK OCEAN, REEF, SHELLS
Because SEAWEED is not linked, the linker issues the following error messages:
%LINK-W-NUDFSYMS, 1 undefined symbol %LINK-I-UDFSYMS, SEAWEED %LINK-W-USEUNDEF, module "OCEAN" references undefined symbol "SEAWEED" %LINK-W-DIAGISUED, completed but with diagnostics
If an error occurs when you link modules, you can often correct it by reentering the command and specifying the correct modules or libraries. If an error indicates that a program module cannot be located, you may be linking the program with the wrong RTL.
For a complete list of linker messages, see the OpenVMS System Messages and Recovery Procedures Reference Manual.