Chapter 6. Linking your program
The following sections describe how to link object files produced by the compiler into either an executable program file (.EXE) or dynamic link library (.DLL).
Every .EXE that you build must contain exactly one main routine, that is, exactly one procedure containing OPTIONS(MAIN). If no main routine exists, the linker complains that your program has no starting address. If more than one main routine exists, the linker complains that there are duplicate references to the name main
.
Every .DLL that you build must have at least one module compiled with the
DLLINIT compile-time option (see “DLLINIT” on page 56).
Starting the linker
Once the compiler has created object modules out of your source files, use the linker to link them together with the PL/I runtime libraries to create an EXE or
DLL file.
Statically linking
To statically link the library into your
.EXE
, specify the LIBS(SINGLE STATIC) or
LIBS(MULTI STATIC) compile-time option (see “LIBS” on page 73). You must also
link with the /NOE linker option.
Linking from the command line
Specify the ILINK command followed by any sequence of options, file names, or directories, separated by space or tab characters.
options
One or more ILINK options. ILINK options start with a / or - character.
filename
The names of one or more of the following kinds of files: v
Object files—have an .OBJ filename extension v
Library files—have an .LIB filename extension v
Definition files—have a .DEF filename extension v
Export files—have an .EXP filename extension v
Resource files—have an .RES filename extension
You must specify at least one object file to use ILINK correctly.
directories
One or more directory locations which end with a / or \ character.
responsefile
The name of a response file. The file name should immediately follow the @ character.
Linking considerations
You can specify the name of the output file with the
/OUT option. You can specify the name of a map file with the
/MAP option.
© Copyright IBM Corp. 1998, 2012
185
Starting the linker
In addition to the libraries you specify, by default the linker searches the PL/I
runtime libraries defined in your object files at compile time (see “LIBS” on page
73).
The directories you specify become part of the linker's search path, before any
directories set in the LIB environment variable. See “Search rules” on page 188 and
“Specifying directories” on page 188 for more information.
You can use wildcard characters to specify multiple object files. For example, use
*.OBJ to specify all the object files in a directory.
Filename extensions are not assumed
The linker does not assume extensions for files. If you specify a filename with no extension, then the linker looks for the file with that name and no extension. If the linker cannot find a file, it stops linking.
Examples
The following command links the object files FUN.OBJ, TEXT.OBJ, TABLE.OBJ, and
CARE.OBJ. The linker searches for unresolved external references in the library file
XLIB.LIB and in the default libraries. Since there is no name provided for the executable file, it is named FUN.EXE, taking the filename of the first object file and the default extension .EXE. The linker also produces a map file, FUNLIST.MAP.
ilink /MAP:funlist fun.obj text.obj table.obj care.obj xlib.lib
The following command links the files MAIN.OBJ, GETDATA.OBJ, and
PRINTIT.OBJ into an executable file named MAIN.EXE, and produces a map file named MAIN.MAP.
ilink /MAP main.obj getdata.obj printit.obj
In Windows, the same command changes slightly by adding an export file,
GETDATA.EXP, which specifies the functions that are exported from
GETDATA.DLL.
ilink getdata.obj printit.obj /OUT:getdata.dll /DLL getdata.exp
Linking from a make file
Use a make file to organize the sequence of actions (such as compiling and linking) required to build your project. You can then invoke all the actions in one step. The
NMAKE utility saves you time by performing actions on only the files that have changed, and on the files that incorporate or depend on the changed files.
The following figure contains a basic make file example.
186
PL/I for Windows Programming Guide
Linker input and output
#
#
#
#
#
#
#
#
#
#
#--------------------------------------------------------
#
# fun.mak - sample makefile
#
Usage: nmake fun.mak
The following commands are done only when needed:
- Compiles fun, text, table, care, xlib1, and xlib2
- Adds xlib1 and xlib2 to library xlib
- Links fun, text, table, care, and xlib to build fun.exe
#
#
#
#
Each block is as follows:
<target>: <list of dependencies for target>
<action(s) required to build target>
#--------------------------------------------------------
OBJS = fun.obj text.obj table.obj care.obj
LIBS = xlib.lib
fun.exe: $(OBJS) $(LIBS) ilink /MAP:funlist $(OBJS) $(LIBS) xlib.lib: xlib1.obj xlib2.obj
ilib /OUT:xlib.lib xlib1.obj xlib2.obj
fun.obj: fun.pli
pli fun.pli
text.obj: text.pli
pli text.pli
table.obj: table.pli
pli table.pli
care.obj: care.pli
pli care.pli
xlib1.obj: xlib1.pli
pli xlib1.pli
xlib2.obj: xlib2.pli
pli xlib2.pli
Figure 4. Make file example
Input and output
The linker is designed to link object files with other library files you specify to produce either an executable program file (.EXE) or a dynamic link library (.DLL).
The linker optionally produces a map file, which provides information about the contents of the executable output.
Input Output
options executable file
(.EXE or .DLL)
object files
(*.OBJ)
map file
(.MAP)
library files
(*.LIB)
return code module definition file
(.DEF)
(Windows)
export files
(*.EXP)
(Windows)
resource files
(*.RES)
Chapter 6. Linking your program
187
Linker input and output
Search rules
When searching for an object (.OBJ), library (.LIB), or module definition (.DEF) file, the linker looks in the following locations in this order:
1.
The directory you specified for the file or the current directory if you did not give a path. Default libraries do not include path specifications.
Note:
If you specify a path with the file, the linker searches only that path.
2.
Any directories entered by themselves on the command line (they must end
with a slash (/) or backslash (\) character). See the section on “Specifying directories” for more information.
3.
Any directories listed in the LIB environment variable.
If the linker cannot locate a file, it generates an error message and stops linking.
Example
A response file could contain the following information:
FUN.OBJ TEXT.OBJ TABLE.OBJ CARE.OBJ
NEWLIBV3.LIB
C:\TESTLIB\
The linker links four object files to create an executable file named FUN.EXE. The linker searches NEWLIBV3.LIB before searching the default libraries to resolve references.
To locate NEWLIBV3.LIB and the default libraries, the linker searches the following locations in this order:
1.
The current directory (because NEWLIBV3.LIB was entered without a path)
2.
The C:\TESTLIB\ directory
3.
The directories listed in the LIB environment variable
Specifying directories
To have the linker search additional directories for input files, specify a drive or directory by itself on the command line. Specify the drive or directory with a slash
(/) or backslash (\) character at the end so the linker will recognize it as a path.
The linker searches the paths you specify before it searches the paths in the LIB
environment variable. See the section on “Search rules” for more information.
Filename defaults
If you do not enter a file name, the linker assumes the following defaults:
Table 7. Linker filename defaults
File Default Filename
Object files
Output file
None. You must enter at least one object file name.
The base name of the first object file.
Map file
Library files
The base name of the output file.
The default libraries defined in the object files. Use the LIBS compile-time option to define the default libraries. Any additional libraries you specify are searched before the default libraries.
Module definition file None. The linker assumes you accept the default for all module statements.
188
PL/I for Windows Programming Guide
Specifying object files
Specifying object files
When you invoke the linker from the command line, the linker assumes that any input it cannot recognize as other files, options, or directories must be an object
file. Use a space or tab character to separate files. See “Linking from the command line” on page 185 for more information on how the linker interprets input.
You can also use wildcard characters to specify multiple object files. For example, use *.OBJ to specify all the object files in a directory.
Using response files
Instead of specifying linker input on the command line, you can put options and filename parameters in a response file. You can combine the response file with options and parameters on the command line.
When you invoke the linker, use the following syntax: ilink @responsefile
The value for
responsefile
is the name of the response file. The @ symbol indicates that the file is a response file. If the file is not in the working directory, specify the path for the file as well as the file name.
You can begin using a response file at any point on the linker command line.
Although multiple response files can be specified on the command line, they cannot be nested.
Options can appear anywhere in the response file. If an option is not valid, the linker generates an error message and stops linking.
Specify the contents of the response file just as you would on the command line.
Because the default syntax identifies input by file extension rather than by position on the command line, it does not matter how many lines there are, or whether there are blank lines in the file.
Example
The response file named FUN.LNK contains the following:
/DEBUG /MAP fun.obj text.obj table.obj care.obj
/exec
/map:funlist graf.lib
When you enter ilink @fun.lnk
, the linker does the following: v Links the four object modules fun.obj
, text.obj
, table.obj
, and care.obj
into an .EXE file named fun.exe
. Because no output type is specified, the linker defaults to .exe.
v
Generates the map file funlist.map
(assuming the extension
.map
).
v
Preserves debugging information (because of the
/DEBUG option).
v
Links any needed routines from the library file graf.lib
, and from the default
PL/I libraries specified in the object files.
Chapter 6. Linking your program
189
Specifying executable output type
Specifying executable output type
You can use the linker to produce executable modules (.EXE) and dynamic link libraries (.DLL). The linker produces .EXE files by default.
Use options to specify what kind of output you want: v
To produce a .DLL, specify the
/DLL option. Or, include the module statement
LIBRARY.
Producing an .EXE file
The linker produces .EXE files by default. Use the
/EXEC option, to explicitly identify the output file as an .EXE file.
An .EXE file is one that can be executed directly. You can run the program by typing the name of the file. In contrast, DLL and device driver programs execute when they are called by other processes, and cannot be run independently. To reduce the size of the .EXE file and improve its performance, use the following options: v /ALIGNFILE:
n
to set the file alignment for sections in the output file. Set
n
to smaller factors to reduce the size of the executable, and to larger factors to reduce load time for the executable. By default, the alignment is set to 512 .
v
/BASE:
n
to specify the load address for the executable. For example, if several
DLLs are loaded at base addresses that ensure that the DLLs do not overlap, the linker does not have to reapply the relocation records.
n
(the load address) must be a multiple of 0x10000, and it cannot be 0.
If you do not specify an extension for the output file name, the linker automatically adds the extension .EXE to the name you provide. If you do not specify an output filename at all, the linker generates an .EXE file with the same filename as the first .OBJ file it linked.
Producing a dynamic link library
A dynamic link library (.DLL) file contains executable code for common functions, just as a library (.LIB) file does. When you link with a DLL (using an import library), the code in the DLL is
not
copied into the executable file. Instead, only the import definitions for DLL functions are copied, resulting in a smaller executable.
At run time, the dynamic link library is loaded into memory, along with the .EXE
file.
To produce a DLL as output, compile at least one object file with the DLLINIT compiler option, and link it with the
/DLL linker option. You must include an export definition (.EXP) file that specifies which functions are to be included in the
DLL.
You can find more information in Chapter 19, “Building dynamic link libraries,” on page 379.
To reduce the size of the DLL and improve its performance, use the following options: v
/ALIGNFILE:value to set the alignment factor in the output file. Set
value
to smaller factors to reduce the size of the DLL, and to larger factors to reduce load time for the DLL. By default, the alignment is set to
512
.
190
PL/I for Windows Programming Guide
Specifying executable output type
For DLLs, setting a /BASE value can save load time when the given load address is available. If the load address is not available, the /BASE value is ignored, and there is no load time benefit.
Once you have produced the DLL, you can produce an executable that links to the
DLL.
The linker determines which functions your object files need during the linking process. Use the ILIB utility to create an import library, and then use the .LIB
file as input to the linker.
Packing executables
Specify
/DBGPACK when you are debugging, to reduce the size of the executable file and potentially improve debugger performance.
Generating a map file
Specify /MAP to generate a map file, which lists the object modules in your output file; section names, addresses, and sizes; and symbol information. If you do not specify a name for the map file, the map file takes the name of the executable output file, with the extension .MAP. To prevent the map file from being generated, use the default, /NOMAP.
Specify /LINENUMBERS to include source file line numbers and associated addresses in the map file.
Linker return codes
4
8
The linker has the following return codes:
Code Meaning
0
The link was completed successfully. The linker detected no errors, and issued no warnings.
Warnings
issued. There may be problems with the output file.
12
16
Errors
detected. The linking might have completed, but the output file cannot be run successfully.
Both warnings issued and errors detected (see return codes 4 and 8)
20
24
28
Severe errors
detected. Linking ended abnormally, and the output file cannot be run successfully.
Both warnings issued and severe errors detected (see return codes 4 and
16)
Both errors and severe errors issued (see return codes 8 and 16)
The linker issued warnings, detected errors, and detected severe errors (see return codes 4, 8, and 16)
If you invoke the linker through a makefile, you can force NMAKE to ignore warnings by putting
-7 before the
ILINK command.
Chapter 6. Linking your program
191
Linker return codes
192
PL/I for Windows Programming Guide
