home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
OS/2 Shareware BBS: 10 Tools
/
10-Tools.zip
/
watc11up.zip
/
core_hlp_os2.zip
/
binp
/
help
/
lguide.inf
(
.txt
)
< prev
next >
Wrap
OS/2 Help File
|
2001-08-28
|
244KB
|
8,954 lines
ΓòÉΓòÉΓòÉ 1. The Watcom Linker ΓòÉΓòÉΓòÉ
The Watcom Linker is a linkage editor (linker) that takes object and library
files as input and produces executable files as output. The following object
module and library formats are supported by the Watcom Linker.
The standard Intel Object Module Format (OMF).
Microsoft's extensions to the standard Intel OMF.
Phar Lap's Easy OMF-386 object module format for linking 386
applications.
The COFF object module format.
The ELF object module format.
The OMF library format.
The AR (Microsoft compatible) object library format.
The Watcom Linker is capable of producing a number of executable file formats.
The following lists these executable file formats.
DOS executable files
ELF executable files
executable files that run under FlashTek's DOS extender
executable files that run under Phar Lap's 386|DOS-Extender
executable files that run under Tenberry Software's DOS/4G and DOS/4GW
DOS extenders
executable files that run under Autodesk's AutoCAD Development System
NetWare Loadable Modules (NLMs) that run under Novell's NetWare 386
operating system
OS/2 executable files including Dynamic Link Libraries
QNX executable files
16-bit Windows (Win16) executable files including Dynamic Link Libraries
32-bit Windows (Win32) executable files including Dynamic Link Libraries
In addition to being able to generate the above executable file formats, the
Watcom Linker also runs under a variety of operating systems. Currently, the
Watcom Linker runs under the following operating systems.
DOS
OS/2
QNX
Windows NT
Windows 95
We refer to the operating system upon which you run the Watcom Linker as the
"host".
The chapter entitled Linking Executable Files for Various Systems summarizes
each of the executable file formats that can be generated by the linker. The
chapter entitled Linker Directives and Options describes all of the linker
directives and options. The remaining chapters describe aspects of each of
the executable file formats.
ΓòÉΓòÉΓòÉ 2. Linking Executable Files for Various Systems ΓòÉΓòÉΓòÉ
The Watcom Linker command line format is as follows.
wlink {directive}
where directive is a series of Watcom Linker directives specified on the
command line or in one or more files. If the directives are contained within a
file, the "@" character is used to reference that file. If no file extension
is specified, a file extension of "lnk" is assumed.
Example:
wlink name testprog @first @second option map
In the above example, directives are specified on the command line (e.g., "name
testprog" and "option map") and in files (e.g., FIRST.LNK and SECOND.LNK).
ΓòÉΓòÉΓòÉ 2.1. Using the SYSTEM Directive ΓòÉΓòÉΓòÉ
For each executable file format that can be created using the Watcom Linker, a
specific SYSTEM directive may be used. The SYSTEM directive selects a subset
of the available directives necessary to create each specific executable file
format.
System
Description
com
16-bit x86 DOS ".COM" executable
dos
16-bit x86 DOS executable
dos4g
32-bit x86 DOS/4GW executable
dos4gnz
non-zero based 32-bit x86 DOS/4GW executable
netware
32-bit x86 NetWare Loadable Module
novell
synonym for "netware"
os2
16-bit x86 OS/2 executable
os2 dll
16-bit x86 OS/2 Dynamic Link Library
os2v2
32-bit x86 OS/2 executable
os2v2 dll
32-bit x86 OS/2 Dynamic Link Library
os2v2_pm
32-bit x86 OS/2 Presentation Manager executable
pharlap
32-bit x86 Phar Lap executable
tnt
32-bit x86 Phar Lap TNT executable
qnx
16-bit x86 QNX executable
qnx386
32-bit x86 QNX executable
x32r
32-bit x86 FlashTek executable using register-based calling conventions
x32rv
32-bit x86 virtual-memory FlashTek executable using register-based
calling conventions
x32s
32-bit x86 FlashTek executable using stack-based calling conventions
x32sv
32-bit x86 virtual-memory FlashTek executable using stack-based calling
conventions
windows
16-bit x86 Windows 3.x executable
windows_dll
16-bit x86 Windows 3.x Dynamic Link Library
win95
32-bit x86 Windows 95 executable
win95 dll
32-bit x86 Windows 95 Dynamic Link Library
nt
32-bit x86 Windows NT character-mode executable
nt_win
32-bit x86 Windows NT windowed executable
win32
synonym for "nt_win"
nt_dll
32-bit x86 Windows NT Dynamic Link Library
win386
32-bit x86 Watcom extended Windows 3.x executable or Dynamic Link Library
ads
32-bit x86 AutoCAD Development System executable
eadi
32-bit x86 Emulation AutoCAD Device Interface
fadi
32-bit x86 Floating-point AutoCAD Device Interface
The various systems that we have listed above are defined in special linker
directive files which are plain ASCII text files that you can edit. These
files are called WLINK.LNK and WLSYSTEM.LNK.
The file WLINK.LNK is a special linker directive file that is automatically
processed by the Watcom Linker before processing any other directives. On a
DOS, OS/2, or Windows-hosted system, this file must be located in one of the
paths specified in the PATH environment variable. On a QNX-hosted system,
this file should be located in the /etc directory. A default version of this
file is located in the \WATCOM\BINW directory on DOS-hosted systems, the
\WATCOM\BINP directory on OS/2-hosted systems, the /etc directory on
QNX-hosted systems, and the \WATCOM\BINNT directory on Windows 95 or Windows
NT-hosted systems. Note that the file WLINK.LNK includes the file
WLSYSTEM.LNK which is located in the \WATCOM\BINW directory on DOS, OS/2, or
Windows-hosted systems and the /etc directory on QNX-hosted systems.
The files WLINK.LNK and WLSYSTEM.LNK reference the WATCOM environment variable
which must be set to the directory in which you installed your software.
In the following sections, we show some of the typical directives that you
might use to create a particular executable file format. The common
directives are described in the chapter entitled Linker Directives and
Options. They are "common" in the sense that they may be used with any
executable format. There are other, less general, directives that may be
specified for a particular executable format. In each of the following
sections, we refer you to chapters in which you will find more information on
the directives available with the executable format used.
At this point, it should be noted that various systems have adopted particular
executable file formats. For example, AutoCAD applications use a Phar Lap
executable file format and both the Tenberry Software DOS/4G(W) and FlashTek
DOS extenders support one of the OS/2 executable file formats. It is for this
reason that you may find that we direct you to a chapter which would, at first
glance, seem unrelated to the executable file format in which you are
interested.
To summarize, the steps that you should follow to learn about creating a
particular executable are:
1. Look for a section in this chapter that describes the executable format
in which you are interested.
2. See the chapter entitled Linker Directives and Options for a description
of the common directives.
3. If you require additional information, see also the chapter to which we
have referred you.
4. Also check the Watcom C/C++ Programmer's Guide or Watcom FORTRAN 77
Programmer's Guide for more information on creating specific types of
applications.
ΓòÉΓòÉΓòÉ 2.2. Linking 16-bit x86 Executable Files ΓòÉΓòÉΓòÉ
The following sections describe how to link a variety of 16-bit executable
files.
ΓòÉΓòÉΓòÉ 2.2.1. Linking 16-bit x86 DOS Executable Files ΓòÉΓòÉΓòÉ
To create this type of file, use the following structure.
system dos
option map
name app_name
file obj1, obj2, ...
library lib1, lib2, ...
For more information, see the chapter entitled DOS: The DOS Executable File
Format.
ΓòÉΓòÉΓòÉ 2.2.2. Linking 16-bit x86 DOS .COM Executable Files ΓòÉΓòÉΓòÉ
To create this type of file, use the following structure.
system com
option map
name app_name
file obj1, obj2, ...
library lib1, lib2, ...
For more information, see the chapter entitled DOS: The DOS Executable File
Format.
ΓòÉΓòÉΓòÉ 2.2.3. Linking 16-bit x86 OS/2 Executable Files ΓòÉΓòÉΓòÉ
To create this type of file, use the following structure.
system os2
option map
name app_name
file obj1, obj2, ...
library lib1, lib2, ...
For more information, see the chapter entitled OS/2: The OS/2 Executable and
DLL File Formats.
ΓòÉΓòÉΓòÉ 2.2.4. Linking 16-bit x86 OS/2 Dynamic Link Libraries ΓòÉΓòÉΓòÉ
To create this type of file, use the following structure.
system os2 dll
option map
name app_name
file obj1, obj2, ...
library lib1, lib2, ...
For more information, see the chapter entitled OS/2: The OS/2 Executable and
DLL File Formats.
ΓòÉΓòÉΓòÉ 2.2.5. Linking 16-bit x86 QNX Executable Files ΓòÉΓòÉΓòÉ
To create this type of file, use the following structure.
system qnx
option map
name app_name
file obj1, obj2, ...
library lib1, lib2, ...
For more information, see the chapter entitled QNX: The QNX Executable File
Format.
ΓòÉΓòÉΓòÉ 2.2.6. Linking 16-bit x86 Windows 3.x Executable Files ΓòÉΓòÉΓòÉ
To create this type of file, use the following structure.
system windows
option map
name app_name
file obj1, obj2, ...
library lib1, lib2, ...
For more information, see the chapter entitled Win16: The Win16 Executable and
DLL File Formats.
ΓòÉΓòÉΓòÉ 2.2.7. Linking 16-bit x86 Windows 3.x Dynamic Link Libraries ΓòÉΓòÉΓòÉ
To create this type of file, use the following structure.
system windows_dll
option map
name app_name
file obj1, obj2, ...
library lib1, lib2, ...
For more information, see the chapter entitled Win16: The Win16 Executable and
DLL File Formats.
ΓòÉΓòÉΓòÉ 2.3. Linking 32-bit x86 Executable Files ΓòÉΓòÉΓòÉ
The following sections describe how to create a variety of 32-bit executable
files.
ΓòÉΓòÉΓòÉ 2.3.1. Linking 32-bit x86 AutoCAD Development System Executable Files ΓòÉΓòÉΓòÉ
To create this type of file, use the following structure.
system ads
option map
name app_name
file obj1, obj2, ...
library lib1, lib2, ...
For more information, see the chapter entitled Phar Lap: The Phar Lap
Executable File Format.
ΓòÉΓòÉΓòÉ 2.3.2. Linking 32-bit x86 AutoCAD Device Interface Executable Files ΓòÉΓòÉΓòÉ
To create this type of file, use the following structure for an emulation
AutoCAD Device Interface.
system eadi
option map
name app_name
file obj1, obj2, ...
library lib1, lib2, ...
To create a floating-point AutoCAD Device Interface, specify
system fadi.
For more information, see the chapter entitled Phar Lap: The Phar Lap
Executable File Format.
ΓòÉΓòÉΓòÉ 2.3.3. Linking 32-bit x86 DOS/4GW Executable Files ΓòÉΓòÉΓòÉ
To create this type of file, use the following structure.
system dos4g
option map
name app_name
file obj1, obj2, ...
library lib1, lib2, ...
For more information, see the chapter entitled OS/2: The OS/2 Executable and
DLL File Formats.
ΓòÉΓòÉΓòÉ 2.3.4. Linking 32-bit x86 FlashTek Executable Files ΓòÉΓòÉΓòÉ
To create these files, use one of the following structures.
system x32r
option map
name app_name
file obj1, obj2, ...
library lib1, lib2, ...
If the system is x32r, a FlashTek executable file is created for an application
using the register calling convention.
system x32rv
option map
name app_name
file obj1, obj2, ...
library lib1, lib2, ...
If the system is x32rv, a virtual-memory FlashTek executable file is created
for an application using the register calling convention.
system x32s
option map
name app_name
file obj1, obj2, ...
library lib1, lib2, ...
If the system is x32s, a FlashTek executable file is created for an application
using the stack calling convention.
system x32sv
option map
name app_name
file obj1, obj2, ...
library lib1, lib2, ...
If the system is x32sv, a virtual-memory FlashTek executable file is created
for an application using the stack calling convention.
For more information, see the chapter entitled OS/2: The OS/2 Executable and
DLL File Formats.
ΓòÉΓòÉΓòÉ 2.3.5. Linking 32-bit x86 Novell NetWare Loadable Modules ΓòÉΓòÉΓòÉ
To create this type of file, use the following structure.
system netware
option map
name app_name
file obj1, obj2, ...
library lib1, lib2, ...
module mod_name
import @%WATCOM%\novi\mod_name.imp
For more information, see the chapter entitled NetWare: The NetWare 386
Executable File Format.
ΓòÉΓòÉΓòÉ 2.3.6. Linking 32-bit x86 OS/2 Executable Files ΓòÉΓòÉΓòÉ
To create this type of file, use the following structure.
system os2v2
option map
name app_name
file obj1, obj2, ...
library lib1, lib2, ...
For more information, see the chapter entitled OS/2: The OS/2 Executable and
DLL File Formats.
ΓòÉΓòÉΓòÉ 2.3.7. Linking 32-bit x86 OS/2 Dynamic Link Libraries ΓòÉΓòÉΓòÉ
To create this type of file, use the following structure.
system os2v2 dll
option map
name app_name
file obj1, obj2, ...
library lib1, lib2, ...
For more information, see the chapter entitled OS/2: The OS/2 Executable and
DLL File Formats.
ΓòÉΓòÉΓòÉ 2.3.8. Linking 32-bit x86 OS/2 Presentation Manager Executable Files ΓòÉΓòÉΓòÉ
To create this type of file, use the following structure.
system os2v2_pm
option map
name app_name
file obj1, obj2, ...
library lib1, lib2, ...
For more information, see the chapter entitled OS/2: The OS/2 Executable and
DLL File Formats.
ΓòÉΓòÉΓòÉ 2.3.9. Linking 32-bit x86 Phar Lap Executable Files ΓòÉΓòÉΓòÉ
To create this type of file, use the following structure.
system pharlap
option map
name app_name
file obj1, obj2, ...
library lib1, lib2, ...
For more information, see the chapter entitled Phar Lap: The Phar Lap
Executable File Format.
ΓòÉΓòÉΓòÉ 2.3.10. Linking 32-bit x86 Phar Lap TNT Executable Files ΓòÉΓòÉΓòÉ
To create this type of file, use the following structure.
system tnt
option map
name app_name
file obj1, obj2, ...
library lib1, lib2, ...
For more information, see the chapter entitled Win32: The Win32 Executable and
DLL File Formats.
ΓòÉΓòÉΓòÉ 2.3.11. Linking 32-bit x86 QNX Executable Files ΓòÉΓòÉΓòÉ
To create this type of file, use the following structure.
system qnx386
option map
name app_name
file obj1, obj2, ...
library lib1, lib2, ...
For more information, see the chapter entitled QNX: The QNX Executable File
Format.
ΓòÉΓòÉΓòÉ 2.3.12. Linking 32-bit x86 Extended Windows 3.x Executable ΓòÉΓòÉΓòÉ
To create this type of file, use the following structure.
system win386
option map
name app_name
file obj1, obj2, ...
library lib1, lib2, ...
After linking this executable, you must bind the Watcom 32-bit Windows-extender
to the executable (a .REX file) to produce a Windows executable (a .EXE file).
wbind -n app_name
For more information, see the chapter entitled Win16: The Win16 Executable and
DLL File Formats.
ΓòÉΓòÉΓòÉ 2.3.13. Linking 32-bit x86 Extended Windows 3.x Dynamic Link Libraries ΓòÉΓòÉΓòÉ
To create this type of file, use the following structure.
system win386
option map
name app_name
file obj1, obj2, ...
library lib1, lib2, ...
After linking this executable, you must bind the Watcom 32-bit Windows-extender
for DLLs to the executable (a .REX file) to produce a Windows Dynamic Link
Library (a .DLL file).
wbind -n -d app_name
For more information, see the chapter entitled Win16: The Win16 Executable and
DLL File Formats.
ΓòÉΓòÉΓòÉ 2.3.14. Linking 32-bit x86 Windows 95 Executable Files ΓòÉΓòÉΓòÉ
To create this type of file, use the following structure.
system win95
option map
name app_name
file obj1, obj2, ...
library lib1, lib2, ...
For more information, see the chapter entitled Win32: The Win32 Executable and
DLL File Formats.
ΓòÉΓòÉΓòÉ 2.3.15. Linking 32-bit x86 Windows 95 Dynamic Link Libraries ΓòÉΓòÉΓòÉ
To create this type of file, use the following structure.
system win95 dll
option map
name app_name
file obj1, obj2, ...
library lib1, lib2, ...
For more information, see the chapter entitled Win32: The Win32 Executable and
DLL File Formats.
ΓòÉΓòÉΓòÉ 2.3.16. Linking 32-bit x86 Windows NT Character-Mode Executable Files ΓòÉΓòÉΓòÉ
To create this type of file, use the following structure.
system nt
option map
name app_name
file obj1, obj2, ...
library lib1, lib2, ...
For more information, see the chapter entitled Win32: The Win32 Executable and
DLL File Formats.
ΓòÉΓòÉΓòÉ 2.3.17. Linking 32-bit x86 Windows NT Windowed Executable Files ΓòÉΓòÉΓòÉ
To create this type of file, use the following structure.
system nt_win
option map
name app_name
file obj1, obj2, ...
library lib1, lib2, ...
For more information, see the chapter entitled Win32: The Win32 Executable and
DLL File Formats.
ΓòÉΓòÉΓòÉ 2.3.18. Linking 32-bit x86 Windows NT Dynamic Link Libraries ΓòÉΓòÉΓòÉ
To create this type of file, use the following structure.
system nt_dll
option map
name app_name
file obj1, obj2, ...
library lib1, lib2, ...
For more information, see the chapter entitled Win32: The Win32 Executable and
DLL File Formats.
ΓòÉΓòÉΓòÉ 3. Linker Directives and Options ΓòÉΓòÉΓòÉ
The Watcom Linker supports a large set of directives and options. The
following sections present these directives and options in alphabetical order.
Not all directives and options are supported for all executable formats. When
a directive or option applies only to a subset of the executable formats that
the linker can generate, the supporting formats are noted. In the following
example, the notation indicates that the directive or option is supported for
all executable formats.
Example:
Formats: All
In the following example, the notation indicates that the directive or option
is supported for OS/2, 16-bit Windows and 32-bit Windows executable formats
only.
Example:
Formats: OS/2, Win16, Win32
Directives tell the Watcom Linker how to create your program. For example,
using directives you can tell the Watcom Linker which object files are to be
included in the program, which library files to search to resolve undefined
references, and the name of the executable file.
The file WLINK.LNK is a special linker directive file that is automatically
processed by the Watcom Linker before processing any other directives. On a
DOS, OS/2, or Windows-hosted system, this file must be located in one of the
paths specified in the PATH environment variable. On a QNX-hosted system, this
file should be located in the /etc directory. A default version of this file
is located in the \WATCOM\BINW directory on DOS-hosted systems, the
\WATCOM\BINP directory on OS/2-hosted systems, the /etc directory on QNX-hosted
systems, and the \WATCOM\BINNT directory on Windows 95 or Windows NT-hosted
systems. Note that the file WLINK.LNK includes the file WLSYSTEM.LNK which is
located in the \WATCOM\BINW directory on DOS, OS/2, or Windows-hosted systems
and the /etc directory on QNX-hosted systems.
The files WLINK.LNK and WLSYSTEM.LNK reference the WATCOM environment variable
which must be set to the directory in which you installed your software.
It is also possible to use environment variables when specifying a directive.
For example, if the LIBDIR environment variable is defined as follows,
set libdir=\test
then the linker directive
library %libdir%\mylib
is equivalent to the following linker directive.
library \test\mylib
Note that a space must precede a reference to an environment variable.
Many directives can take a list of one or more arguments separated by commas.
Instead of a comma-delimited list, you can specify a space-separated list
provided the list is enclosed in braces (e.g., { space delimited list }). For
example, the "FILE" directive can take a list of object file names as an
argument.
file first,second,third,fourth
The alternate way of specifying this is as follows.
file {first second third fourth}
Where this comes in handy is in make files, where a list of dependents is
usually a space-delimited list.
OBJS = first second third fourth
.
.
.
wlink file {$(objs)}
The following notation is used to describe the syntax of linker directives and
options.
ABC
All items in upper case are required.
[abc]
The item abc is optional.
{abc}
The item abc may be repeated zero or more times.
{abc}+
The item abc may be repeated one or more times.
a|b|c
One of a, b or c may be specified.
a ::= b
The item a is defined in terms of b.
Certain characters have special meaning to the linker. When a special
character must appear in a name, you can imbed the string that makes up the
name inside apostrophes (e.g., 'name@8'). This prevents the linker from
interpreting the special character in its usual manner. This is also true for
file or path names that contain spaces (e.g., '\program
files\software\mylib'). Normally, the linker would interpret a space or blank
in a file name as a separator. The special characters are listed below:
+-----------+-----------------------+
| Character | Name of Character |
+-----------+-----------------------+
| | Blank |
| = | Equals |
| ( | Left Parenthesis |
| ) | Right Parenthesis |
| , | Comma |
| . | Period |
| { | Left Brace |
| } | Right Brace |
| @ | At Sign |
| # | Hash Mark |
| % | Percentage Symbol |
+-----------+-----------------------+
ΓòÉΓòÉΓòÉ 3.1. The ALIAS Directive ΓòÉΓòÉΓòÉ
Formats: All
The "ALIAS" directive is used to specify an equivalent name for a symbol name.
The format of the "ALIAS" directive (short form "A") is as follows.
ALIAS alias_name=symbol_name{, alias_name=symbol_name}
where
description
alias_name
is the alias name.
symbol_name
is the symbol name to which the alias name is mapped.
Consider the following example.
alias sine=mysine
When the linker tries to resolve the reference to sine, it will immediately
substitute the name mysine for sine and begin searching for the symbol mysine.
ΓòÉΓòÉΓòÉ 3.2. The ALIGNMENT Option ΓòÉΓòÉΓòÉ
Formats: ELF, OS/2, Win16, Win32
The "ALIGNMENT" option specifies the alignment for segments in the executable
file. The format of the "ALIGNMENT" option (short form "A") is as follows.
OPTION ALIGNMENT=n
where
description
n
represents a value. The complete form of n is the following.
[0x]d{d}[k|m]
d represents a decimal digit. If 0x is specified, the string of digits
represents a hexadecimal number. If k is specified, the value is
multiplied by 1024. If m is specified, the value is multiplied by
1024*1024.
n specifies the alignment for segments in the executable file and must be a
power of 2.
In 16-bit applications, segments in the executable file are pointed to by a
segment table. An entry in the segment table contains a 16-bit value which is
a multiple of the alignment value. Together they form the offset of the
segment from the start of the segment table. Note that the smaller the value
of n the smaller the executable file.
By default, the Watcom Linker will automatically choose the smallest value of
n possible. You need not specify this option unless you want padding between
segments in the executable file.
ΓòÉΓòÉΓòÉ 3.3. The ANONYMOUSEXPORT Directive ΓòÉΓòÉΓòÉ
Formats: Win16, Win32
The "ANONYMOUSEXPORT" directive is an alternative to the "EXPORT" directive
described in The EXPORT Directive. The symbol associated with this name will
not appear in either the resident or the non-resident names table. The entry
point is, however, still available for ordinal linking.
The format of the "ANONYMOUSEXPORT" directive (short form "ANON") is as
follows.
ANONYMOUSEXPORT export{,export}
or
ANONYMOUSEXPORT =lbc_file
export ::= entry_name[.ordinal][=internal_name]
where
description
entry_name
is the name to be used by other applications to call the function.
ordinal
is an ordinal value for the function. If the ordinal number is
specified, other applications can reference the function by using this
ordinal number.
internal_name
is the actual name of the function and should only be specified if it
differs from the entry name.
lbc_file
is a file specification for the name of a librarian command file. If no
file extension is specified, a file extension of "lbc" is assumed. The
linker will process the librarian command file and look for commands to
the librarian that are used to create import library entries. These
commands have the following form.
++sym.dll_name[.[altsym].export_name][.ordinal]
where
description
sym
is the name of a symbol in a Dynamic Link Library.
dll_name
is the name of the Dynamic Link Library that defines sym.
altsym
is the name of a symbol in a Dynamic Link Library. When
omitted, the default symbol name is sym.
export_name
is the name that an application that is linking to the Dynamic
Link Library uses to reference sym. When omitted, the default
export name is sym.
ordinal
is the ordinal value that can be used to identify sym instead
of using the name export_name.
All other librarian commands will be ignored.
Notes:
1. By default, the Watcom C and C++ compilers append an underscore ('_') to
all function names. This should be considered when specifying entry_name
and internal_name in an "ANONYMOUSEXPORT" directive.
2. If the name contains characters that are special to the linker then the
name may be placed inside apostrophes (e.g., anonymousexport 'myfunc@8').
3. The symbol associated with the entry name will not appear in either the
resident or the non-resident names table. The entry point is, however,
still available for ordinal linking. This directive is important when
you wish to reduce the number of entries that are placed in the resident
and non-resident names table.
ΓòÉΓòÉΓòÉ 3.4. The ARTIFICIAL Option ΓòÉΓòÉΓòÉ
Formats: All
The "ARTIFICIAL" option should only be used if you are developing a Watcom C++
application. A Watcom C++ application contains many compiler-generated
symbols. By default, the linker does not include these symbols in the map
file. The "ARTIFICIAL" option can be used if you wish to include these
compiler-generated symbols in the map file.
The format of the "ARTIFICIAL" option (short form "ART") is as follows.
OPTION ARTIFICIAL
ΓòÉΓòÉΓòÉ 3.5. The CACHE Option ΓòÉΓòÉΓòÉ
Formats: All
The "CACHE" and "NOCACHE" options can be used to control caching of object and
library files in memory by the linker. When neither the "CACHE" nor "NOCACHE"
option is specified, the linker will only cache small libraries. Object files
and large libraries are not cached. The "CACHE" and "NOCACHE" options can be
used to alter this default behaviour. The "CACHE" option enables the caching
of object files and large library files while the "NOCACHE" option disables all
caching.
The format of the "CACHE" option (short form "CAC") is as follows.
OPTION CACHE
The format of the "NOCACHE" option (short form "NOCAC") is as follows.
OPTION NOCACHE
When linking large applications with many object files, caching object files
will cause extensive use of memory by the linker. On virtual memory systems
such as OS/2, Windows NT or Windows 95, this can cause extensive page file
activity when real memory resources have been exhausted. This can degrade the
performance of other tasks on your system. For this reason, the OS/2 and
Windows-hosted versions of the linker do not perform object file caching by
default. This does not imply that object file caching is not beneficial. If
your system has lots of real memory or the linker is running as the only task
on the machine, object file caching can certainly improve the performance of
the linker.
On single-tasking environments such as DOS, the benefits of improved linker
performance outweighs the memory demands associated with object file caching.
For this reason, object file caching is performed by default on these systems.
If the memory requirements of the linker exceed the amount of memory on your
system, the "NOCACHE" option can be specified.
The QNX operating system is a multi-tasking real-time operating system.
However, it is not a virtual memory system. Caching object files can consume
large amounts of memory. This may prevent other tasks on the system from
running, a problem that may be solved by using the "NOCACHE" option.
ΓòÉΓòÉΓòÉ 3.6. The CASEEXACT Option ΓòÉΓòÉΓòÉ
Formats: All
The "CASEEXACT" option tells the Watcom Linker to respect case when resolving
references to global symbols. That is, "ScanName" and "SCANNAME" represent two
different symbols. By default, the linker is case insensitive; "ScanName" and
"SCANNAME" represent the same symbol. The format of the "CASEEXACT" option
(short form "C") is as follows.
OPTION CASEEXACT
If you have specified the "CASEEXACT" option in the default directive files
WLINK.LNK or WLSYSTEM.LNK, it is possible to override this option by using the
"NOCASEEXACT" option. The "NOCASEEXACT" option turns off case-sensitive
linking. The format of the "NOCASEEXACT" option (short form "NOCASE") is as
follows.
OPTION NOCASEEXACT
The file WLINK.LNK is a special linker directive file that is automatically
processed by the Watcom Linker before processing any other directives. On a
DOS, OS/2, or Windows-hosted system, this file must be located in one of the
paths specified in the PATH environment variable. On a QNX-hosted system, this
file should be located in the /etc directory. A default version of this file
is located in the \WATCOM\BINW directory on DOS-hosted systems, the
\WATCOM\BINP directory on OS/2-hosted systems, the /etc directory on QNX-hosted
systems, and the \WATCOM\BINNT directory on Windows 95 or Windows NT-hosted
systems. Note that the file WLINK.LNK includes the file WLSYSTEM.LNK which is
located in the \WATCOM\BINW directory on DOS, OS/2, or Windows-hosted systems
and the /etc directory on QNX-hosted systems.
The files WLINK.LNK and WLSYSTEM.LNK reference the WATCOM environment variable
which must be set to the directory in which you installed your software.
ΓòÉΓòÉΓòÉ 3.7. The CHECK Option ΓòÉΓòÉΓòÉ
Formats: NetWare
The "CHECK" option specifies the name of a procedure to execute before an NLM
is unloaded. This procedure can, for example, inform the operator that the NLM
is in use and prevent it from being unloaded.
The format of the "CHECK" option (short form "CH") is as follows.
OPTION CHECK=symbol_name
where
description
symbol_name
specifies the name of a procedure to execute before the NLM is unloaded.
If the "CHECK" option is not specified, no check procedure will be called.
ΓòÉΓòÉΓòÉ 3.8. The # Directive ΓòÉΓòÉΓòÉ
Formats: All
The "#" directive is used to mark the start of a comment. All text from the
"#" character to the end of the line is considered a comment. The format of
the "#" directive is as follows.
# comment
where
description
comment
is any sequence of characters.
The following directive file illustrates the use of comments.
file main, trigtest
# Use my own version of "sin" instead of the
# library version.
file mysin
library \math\trig
ΓòÉΓòÉΓòÉ 3.9. The COMMIT Directive ΓòÉΓòÉΓòÉ
Formats: Win32
When the operating system allocates the stack and heap for an application, it
does not actually allocate the whole stack and heap to the application when it
is initially loaded. Instead, only a portion of the stack and heap are
allocated or committed to the application. Any part of the stack and heap that
is not committed will be committed on demand.
The format of the "COMMIT" directive (short form "COM") is as follows.
COMMIT mem_type
mem_type ::= STACK=n | HEAP=n
where
description
n
represents a value. The complete form of n is the following.
[0x]d{d}[k|m]
d represents a decimal digit. If 0x is specified, the string of digits
represents a hexadecimal number. If k is specified, the value is
multiplied by 1024. If m is specified, the value is multiplied by
1024*1024.
n represents the amout of stack or heap that is initially committed to
the application. The short form for "STACK" is "ST" and the short form
for "HEAP" is "H".
If you do not specify the "COMMIT HEAP" directive then a 4k heap is committed
to the application.
If you do not specify the "COMMIT STACK" directive then the default size is
the smaller of 64K or the size specified by the "STACK" option. See the
section entitled The STACK Option for more information on specifying a stack
size.
ΓòÉΓòÉΓòÉ 3.10. The COPYRIGHT Option ΓòÉΓòÉΓòÉ
Formats: NetWare
The "COPYRIGHT" option specifies copyright information that is placed in the
executable file. The format of the "COPYRIGHT" option (short form "COPYR") is
as follows.
OPTION COPYRIGHT 'string'
where
description
string
specifies the copyright information.
ΓòÉΓòÉΓòÉ 3.11. The CUSTOM Option ΓòÉΓòÉΓòÉ
Formats: NetWare
The format of the "CUSTOM" option (short form "CUST") is as follows.
OPTION CUSTOM=file_name
where
description
file_name
specifies the file name of the custom data file.
The custom data file is placed into the executable file when the application
is linked but is really not part of the program. When the application is
loaded into memory, the information extracted from a custom data file is not
loaded into memory. Instead, information is passed to the program (as
arguments) which allows the access and processing of this information.
ΓòÉΓòÉΓòÉ 3.12. The CVPACK Option ΓòÉΓòÉΓòÉ
Formats: All
This option is only meaningful when generating Microsoft Codeview debugging
information. This option causes the linker to automatically run the Watcom
Codeview 4 Symbolic Debugging Information Compactor, CVPACK, on the executable
that it has created. This is necessary to get the Codeview debugging
information into a state where the Microsoft Codeview debugger will accept it.
The format of the "CVPACK" option (short form "CVP") is as follows.
OPTION CVPACK
For more information on generating Codeview debugging information into the
executable, see the section entitled The DEBUG Directive
ΓòÉΓòÉΓòÉ 3.13. The DEBUG Directive ΓòÉΓòÉΓòÉ
Formats: All
The "DEBUG" directive is used to tell the Watcom Linker to generate debugging
information in the executable file. This extra information in the executable
file is used by the Watcom Debugger. The format of the "DEBUG" directive
(short form "D") is as follows.
DEBUG dbtype [dblist] |
DEBUG [dblist]
db_type ::= DWARF | WATCOM | CODEVIEW | NOVELL
db_list ::= [db_option{,db_option}]
db_option ::= LINES | TYPES | LOCALS | ALL
DEBUG NOVELL only
db_option ::= ONLYEXPORTS | REFERENCED
The Watcom Linker supports four types of debugging information, "DWARF" (the
default), "WATCOM", "CODEVIEW", or "NOVELL".
DWARF
(short form "D") specifies that all object files contain Dwarf format
debugging information and that the executable file will contain Dwarf
debugging information.
This debugging format is assumed by default when none is specified.
WATCOM
(short form "W") specifies that all object files contain WATCOM format
debugging information and that the executable file will contain WATCOM
debugging information. This format permits the selection of specific
classes of debugging information ( db_list) which are described below.
CODEVIEW
(short form "C") specifies that all object files contain Codeview (CV4)
format debugging information and that the executable file will contain
Codeview debugging information.
It will be necessary to run the Microsoft Debugging Information
Compactor, CVPACK, on the executable that it has created. For
information on requesting the linker to automatically run CVPACK, see the
section entitled The CVPACK Option Alternatively, you can run CVPACK from
the command line.
NOVELL
(short form "N") specifies a form of global symbol information that can
only be processed by the NetWare 386 debugger.
For the WATCOM debugging information format, we can be selective about the
types of debugging information that we include with the executable file. We
can categorize the types of debugging information as follows:
global symbol information
line numbering information
local symbol information
typing information
NetWare 386 global symbol information
The following options can be used with the "DEBUG WATCOM" directive to control
which of the above classes of debugging information is included in the
executable file.
LINES
(short form "LI") specifies line numbering and global symbol information.
LOCALS
(short form "LO") specifies local and global symbol information.
TYPES
(short form "T") specifies typing and global symbol information.
ALL
(short form "A") specifies all of the above debugging information.
ONLYEXPORTS
(short form "ONL") restricts the generation of global symbol information
to exported symbols. This option may only be used with Netware
executable formats.
The following options can be used with the "DEBUG NOVELL" directive to control
which of the above classes of debugging information is included in the
executable file.
ONLYEXPORTS
(short form "ONL") restricts the generation of global symbol information
to exported symbols.
REFERENCED
(short form "REF") restricts the generation of symbol information to
referenced symbols only.
ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
Note: The position of the "DEBUG" directive is important. The level of
debugging information specified in a "DEBUG" directive only applies to object
files and libraries that appear in subsequent "FILE" or "LIBRARY" directives.
For example, if "DEBUG WATCOM ALL" was the only "DEBUG" directive specified
and was also the last linker directive, no debugging information would appear
in the executable file.
ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
Only global symbol information is actually produced by the Watcom Linker; the
other three classes of debugging information are extracted from object modules
and copied to the executable file. Therefore, at compile time, you must
instruct the compiler to generate local symbol, line numbering and typing
information in the object file so that the information can be transferred to
the executable file. If you have asked the Watcom Linker to produce a
particular class of debugging information and it appears that none is present,
one of the following conditions may exist.
1. The debugging information is not present in the object files.
2. The "DEBUG" directive has been misplaced.
The following sections describe the classes of debugging information.
ΓòÉΓòÉΓòÉ 3.13.1. Line Numbering Information - DEBUG WATCOM LINES ΓòÉΓòÉΓòÉ
The "DEBUG WATCOM LINES" option controls the processing of line numbering
information. Line numbering information is the line number and address of the
generated code for each line of source code in a particular module. This
allows Watcom Debugger to perform source-level debugging. When the Watcom
Linker encounters a "DEBUG WATCOM" directive with a "LINES" or "ALL" option,
line number information for each subsequent object module will be placed in the
executable file. This includes all object modules extracted from object files
specified in subsequent "FILE" directives and object modules extracted from
libraries specified in subsequent "LIBRARY" or "FILE" directives.
ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
Note: All modules for which line numbering information is requested must have
been compiled with the "d1" or "d2" option.
ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
A subsequent "DEBUG WATCOM" directive without a "LINES" or "ALL" option
terminates the processing of line numbering information.
ΓòÉΓòÉΓòÉ 3.13.2. Local Symbol Information - DEBUG WATCOM LOCALS ΓòÉΓòÉΓòÉ
The "DEBUG WATCOM LOCALS" option controls the processing of local symbol
information. Local symbol information is the name and address of all symbols
local to a particular module. This allows Watcom Debugger to locate these
symbols so that you can reference local data and routines by name. When the
Watcom Linker encounters a "DEBUG WATCOM" directive with a "LOCALS" or "ALL"
option, local symbol information for each subsequent object module will be
placed in the executable file. This includes all object modules extracted from
object files specified in subsequent "FILE" directives and object modules
extracted from libraries specified in subsequent "LIBRARY" or "FILE"
directives.
ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
Note: All modules for which local symbol information is requested must have
been compiled with the "d2" option.
ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
A subsequent "DEBUG WATCOM" directive without a "LOCALS" or "ALL" option
terminates the processing of local symbol information.
ΓòÉΓòÉΓòÉ 3.13.3. Typing Information - DEBUG WATCOM TYPES ΓòÉΓòÉΓòÉ
The "DEBUG WATCOM TYPES" option controls the processing of typing information.
Typing information includes a description of all types, structures and arrays
that are defined in a module. This allows Watcom Debugger to display variables
according to their type. When the Watcom Linker encounters a "DEBUG WATCOM"
directive with a "TYPES" or "ALL" option, typing information for each
subsequent object module will be placed in the executable file. This includes
all object modules extracted from object files specified in subsequent "FILE"
directives and object modules extracted from libraries specified in subsequent
"LIBRARY" or "FILE" directives.
ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
Note: All modules for which typing information is requested must have been
compiled with the "d2" option.
ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
A subsequent "DEBUG WATCOM" directive without a "TYPES" or "ALL" option
terminates the processing of typing information.
ΓòÉΓòÉΓòÉ 3.13.4. All Debugging Information - DEBUG WATCOM ALL ΓòÉΓòÉΓòÉ
The "DEBUG WATCOM ALL" option specifies that "LINES", "LOCALS", and "TYPES"
options are requested. The "LINES" option controls the processing of line
numbering information. The "LOCALS" option controls the processing of local
symbol information. The "TYPES" option controls the processing of typing
information. Each of these options is described in a previous section. A
subsequent "DEBUG WATCOM " directive without an "ALL" option discontinues those
options which are not specified in the list of debug options.
ΓòÉΓòÉΓòÉ 3.13.5. Global Symbol Information ΓòÉΓòÉΓòÉ
Global symbol information consists of all the global symbols in your program
and their address. This allows Watcom Debugger to locate these symbols so that
you can reference global data and routines by name. When the Watcom Linker
encounters a "DEBUG" directive, global symbol information for all the global
symbols appearing in your program is placed in the executable file.
ΓòÉΓòÉΓòÉ 3.13.6. Global Symbols for the NetWare 386 Debugger - DEBUG NOVELL ΓòÉΓòÉΓòÉ
The NetWare 386 operating system has a built-in debugger that can be used to
debug programs. When "DEBUG NOVELL" is specified, the Watcom Linker will
generate global symbol information that can be used by the NetWare 386
debugger. Note that any line numbering, local symbol, and typing information
generated in the executable file will not be recognized by the NetWare 386
debugger. Also, WSTRIP cannot be used to remove this form of global symbol
information from the executable file.
ΓòÉΓòÉΓòÉ 3.13.7. The ONLYEXPORTS Debugging Option ΓòÉΓòÉΓòÉ
The "ONLYEXPORTS" option (short form "ONL") restricts the generation of global
symbol information to exported symbols (symbols appearing in an "EXPORT"
directive). If "DEBUG WATCOM ONLYEXPORTS" is specified, Watcom Debugger global
symbol information is generated only for exported symbols. If "DEBUG NOVELL
ONLYEXPORTS" is specified, NetWare 386 global symbol information is generated
only for exported symbols.
ΓòÉΓòÉΓòÉ 3.13.8. Using DEBUG Directives ΓòÉΓòÉΓòÉ
Consider the following directive file.
debug watcom all
file module1
debug watcom lines
file module2, module3
debug watcom
library mylib
It specifies that the following debugging information is to be generated in the
executable file.
1. global symbol information for your program
2. line numbering, typing and local symbol information for the following
object files:
module1.obj
3. line numbering information for the following object files:
module2.obj
module3.obj
Note that if the "DEBUG WATCOM" directive before the "LIBRARY" directive is
not specified, line numbering information for all object modules extracted
from the library "mylib.lib" would be generated in the executable file
provided the object modules extracted from the library have line numbering
information present.
ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
Note: A "DEBUG WATCOM" directive with no option suppresses the processing of
line numbering, local symbol and typing information for all subsequent object
modules.
ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
Debugging information can use a significant amount of disk space. As shown in
the above example, you can select only the class of debugging information you
want and for those modules you wish to debug. In this way, the amount of
debugging information in the executable file is minimized and hence the amount
of disk space used by the executable file is kept to a minimum.
As you can see from the above example, the position of the "DEBUG WATCOM"
directive is important when describing the debugging information that is to
appear in the executable file.
ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
Note: If you want all classes of debugging information for all files to
appear in the executable file you must specify "DEBUG WATCOM ALL" before any
"FILE" and "LIBRARY" directives.
ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
ΓòÉΓòÉΓòÉ 3.13.9. Removing Debugging Information from an Executable File ΓòÉΓòÉΓòÉ
A utility called WSTRIP has been provided which takes as input an executable
file and removes the debugging information placed in the executable file by the
Watcom Linker. Note that global symbol information generated using "DEBUG
NOVELL" cannot be removed by WSTRIP.
For more information on this utility, see the chapter entitled "The Watcom
Strip Utility" in the Watcom C/C++ Tools User's Guide or Watcom FORTRAN 77
Tools User's Guide.
ΓòÉΓòÉΓòÉ 3.14. The DESCRIPTION Option ΓòÉΓòÉΓòÉ
Formats: OS/2, Win16, Win32
The "DESCRIPTION" option inserts the specified text into the application or
Dynamic Link Library. This is useful if you wish to embed copyright
information into an application or Dynamic Link Library. The format of the
"DESCRIPTION" option (short form "DE") is as follows.
OPTION DESCRIPTION 'string'
where
description
string
is the sequence of characters to be embedded into the application or
Dynamic Link Library.
ΓòÉΓòÉΓòÉ 3.15. The DISABLE Directive ΓòÉΓòÉΓòÉ
Formats: All
The "DISABLE" directive is used to disable the display of linker messages.
The Watcom Linker issues three classes of messages; fatal errors, errors and
warnings. Each message has a 4-digit number associated with it. Fatal
messages start with the digit 3, error messages start with the digit 2, and
warning messages start with the digit 1. It is possible for a message to be
issued as a warning or an error.
If a fatal error occurs, the linker will terminate immediately and no
executable file will be generated.
If an error occurs, the linker will continue to execute so that all possible
errors are issued. However, no executable file will be generated since these
errors do not permit a proper executable file to be generated.
If a warning occurs, the linker will continue to execute. A warning message is
usually informational and does not prevent the creation of a proper executable
file. However, all warnings should eventually be corrected.
Note that the behaviour of the linker does not change when a message is
disabled. For example, if a message that normally terminates the linker is
disabled, the linker will still terminate but the message describing the reason
for the termination will not be displayed. For this reason, you should only
disable messages that are warnings.
The linker will ignore the severity of the message number. For example, some
messages can be displayed as errors or warnings. It is not possible to disable
the message when it is issued as a warning and display the message when it is
issued as an error. In general, do not specify the severity of the message
when specifying a message number.
The format of the "DISABLE" directive (short form "DISA") is as follows.
DISABLE msg_num{, msg_num}
where
description
msg_num
is a message number. See the chapter entitled Watcom Linker Diagnostic
Messages for a list of messages and their corresponding numbers.
The following "DISABLE" directive will disable message 28 (an undefined symbol
has been referenced).
disable 28
ΓòÉΓòÉΓòÉ 3.16. The DOSSEG Option ΓòÉΓòÉΓòÉ
Formats: All
The "DOSSEG" option tells the Watcom Linker to order segments in a special way.
The format of the "DOSSEG" option (short form "D") is as follows.
OPTION DOSSEG
When the "DOSSEG" option is specified, segments will be ordered in the
following way.
1. all segments not belonging to group "DGROUP" with class "CODE"
2. all other segments not belonging to group "DGROUP"
3. all segments belonging to group "DGROUP" with class "BEGDATA"
4. all segments belonging to group "DGROUP" not with class "BEGDATA", "BSS"
or "STACK"
5. all segments belonging to group "DGROUP" with class "BSS"
6. all segments belonging to group "DGROUP" with class "STACK"
A special segment belonging to class "BEGDATA" is defined when linking with
Watcom run-time libraries. This segment is initialized with the hexadecimal
byte pattern "01" and is the first segment in group "DGROUP" so that storing
data at location 0 can be detected.
Segments belonging to class "BSS" contain uninitialized data. Note that this
only includes uninitialized data in segments belonging to group "DGROUP".
Segments belonging to class "STACK" are used to define the size of the stack
used for your application. Segments belonging to the classes "BSS" and
"STACK" are last in the segment ordering so that uninitialized data need not
take space in the executable file.
When using Watcom run-time libraries, it is not necessary to specify the
"DOSSEG" option. One of the object files in the Watcom run-time libraries
contains a special record that specifies the "DOSSEG" option.
If no "DOSSEG" option is specified, segments are ordered in the order they are
encountered by the Watcom Linker.
When the "DOSSEG" option is specified, the Watcom Linker defines two special
variables. _edata defines the start of the "BSS" class of segments and _end
defines the end of the "BSS" class of segments. Your program must not
redefine these symbols.
ΓòÉΓòÉΓòÉ 3.17. The ELIMINATE Option ΓòÉΓòÉΓòÉ
Formats: All
The "ELIMINATE" option can be used to enable dead code elimination. Dead code
elimination is a process the linker uses to remove unreferenced segments from
the application. The linker will only remove segments that contain code;
unreferenced data segments will not be removed.
The format of the "ELIMINATE" option (short form "EL") is as follows.
OPTION ELIMINATE
Linking C/C++ Applications
Typically, a module of C/C++ code contains a number of functions. When
this module is compiled, all functions will be placed in the same code
segment. The chances of each function in the module being unreferenced
are remote and the usefulness of the "ELIMINATE" option is greatly
reduced.
In order to maximize the effect of the "ELIMINATE" option, the "zm"
compiler option is available to tell the Watcom C/C++ compiler to place
each function in its own code segment. This allows the linker to remove
unreferenced functions from modules that contain many functions.
Note, that if a function is referenced by data, as in a jump table, the
linker will not be able to eliminate the code for the function even if
the data that references it is unreferenced.
Linking FORTRAN 77 Applications
The Watcom FORTRAN 77 compiler always places each function and subroutine
in its own code segment, even if they are contained in the same module.
Therefore when linking with the "ELIMINATE" option the linker will be
able to eliminate code on a function/subroutine basis.
ΓòÉΓòÉΓòÉ 3.18. The ENDLINK Directive ΓòÉΓòÉΓòÉ
Formats: All
The "ENDLINK" directive is used to indicate the end of a new set of linker
commands that are to be processed after the current set of commands has been
processed. The format of the "ENDLINK" directive (short form "ENDL") is as
follows.
ENDLINK
The "STARTLINK" directive, described in The STARTLINK Directive, is used to
indicate the start of the set of commands.
ΓòÉΓòÉΓòÉ 3.19. The EXIT Option ΓòÉΓòÉΓòÉ
Formats: NetWare
The format of the "EXIT" option (short form "EX") is as follows.
OPTION EXIT=symbol_name
where
description
symbol_name
specifies the name of the procedure that is executed when an NLM is
unloaded.
The default name of the exit procedure is "_Stop".
Note that the exit procedure cannot prevent the NLM from being unloaded. Once
the exit procedure has executed, the NLM will be unloaded. The "CHECK" option
can be used to specify a check procedure that can prevent an NLM from being
unloaded.
ΓòÉΓòÉΓòÉ 3.20. The EXPORT Directive ΓòÉΓòÉΓòÉ
Formats: ELF, NetWare, OS/2, Win16, Win32
The "EXPORT" directive is used to tell the Watcom Linker which symbols are
available for import by other executables.
ΓòÉΓòÉΓòÉ 3.20.1. EXPORT - OS/2, Win16, Win32 only ΓòÉΓòÉΓòÉ
The "EXPORT" directive can be used to define the names and attributes of
functions in Dynamic Link Libraries that are to be exported. An "EXPORT"
definition must be specified for every Dynamic Link Library function that is to
be made available externally.
Win16:
An "EXPORT" directive is also required for the "window function". This
function must be defined by all programs and is called by Windows to
provide information to the program. For example, the window function is
called when a window is created, destroyed or resized, when an item is
selected from a menu, or when a scroll bar is being clicked with a mouse.
The format of the "EXPORT" directive (short form "EXP") is as follows.
EXPORT export{,export}
or
EXPORT =lbc_file
OS/2 only:
export ::= entry_name[.ordinal][=internal_name]
[PRIVATE] [RESIDENT] [iopl_bytes]
Win16, Win32 only:
export ::= entry_name[.ordinal][=internal_name]
[PRIVATE] [RESIDENT]
where
description
entry_name
is the name to be used by other applications to call the function.
ordinal
is an ordinal value for the function. If the ordinal number is
specified, other applications can reference the function by using this
ordinal number.
internal_name
is the actual name of the function and should only be specified if it
differs from the entry name.
PRIVATE
(no short form ) specifies that the function's entry name should be
included in the DLL's export table, but not included in any import
library that the linker generates.
RESIDENT
(short form "RES") specifies that the function's entry name should be
kept resident in memory (i.e., added to the resident names table).
By default, the entry name is always made memory resident if an ordinal
is not specified (i.e., it is implicitly RESIDENT). For 16-bit Windows,
the limit on the size of the resident names table is 64K bytes. Memory
resident entry names allow the operating system to resolve calls more
efficiently when the call is by entry name rather than by ordinal.
If an ordinal is specified and RESIDENT is not specified, the entry name
is added to the non-resident names table (i.e., it is implicitly
non-RESIDENT). If both the ordinal and the RESIDENT keyword are
specified, the symbol is placed in the resident names table.
If you do not want an entry name to appear in either the resident or
non-resident names table, you can use the "ANONYMOUSEXPORT" directive
described in The ANONYMOUSEXPORT Directive.
iopl_bytes
(OS/2 only) is required for functions that execute with I/O privilege.
iopl_bytes specifies that total size of the function's arguments in
bytes. When such a function is executed, the specified number of bytes
is copied from the caller's stack to the I/O-privileged function's stack.
The maximum number of bytes allowed is 63.
lbc_file
is a file specification for the name of a librarian command file. If no
file extension is specified, a file extension of "lbc" is assumed. The
linker will process the librarian command file and look for commands to
the librarian that are used to create import library entries. These
commands have the following form.
++sym.dll_name[.[altsym].export_name][.ordinal]
where
description
sym
is the name of a symbol in a Dynamic Link Library.
dll_name
is the name of the Dynamic Link Library that defines sym.
altsym
is the name of a symbol in a Dynamic Link Library. When
omitted, the default symbol name is sym.
export_name
is the name that an application that is linking to the Dynamic
Link Library uses to reference sym. When omitted, the default
export name is sym.
ordinal
is the ordinal value that can be used to identify sym instead
of using the name export_name.
All other librarian commands will be ignored.
Notes:
1. By default, the Watcom C and C++ compilers append an underscore ('_') to
all function names. This should be considered when specifying entry_name
and internal_name in an "EXPORT" directive.
2. If the name contains characters that are special to the linker then the
name may be placed inside apostrophes (e.g., export 'myfunc@8').
3. If the __export declspec modifier is used in the source code, it is the
equivalent of using the following linker directive:
EXPORT entry_name RESIDENT
ΓòÉΓòÉΓòÉ 3.20.2. EXPORT - ELF only ΓòÉΓòÉΓòÉ
The "EXPORT" directive is used to tell the Watcom Linker which symbols are
available for import by other executables. The format of the "EXPORT"
directive (short form "EXP") is as follows.
EXPORT entry_name{,entry_name}
where
description
entry_name
is the name of the exported symbol.
Notes:
1. By default, the Watcom C and C++ compilers append an underscore ('_') to
all function names. This should be considered when specifying entry_name
in an "EXPORT" directive.
2. If the name contains characters that are special to the linker then the
name may be placed inside apostrophes (e.g., export 'myfunc@8').
ΓòÉΓòÉΓòÉ 3.20.3. EXPORT - Netware only ΓòÉΓòÉΓòÉ
The "EXPORT" directive is used to tell the Watcom Linker which symbols are
available for import by other NLMs. The format of the "EXPORT" directive
(short form "EXP") is as follows.
EXPORT entry_name{,entry_name}
where
description
entry_name
is the name of the exported symbol.
Notes:
1. If the name contains characters that are special to the linker then the
name may be placed inside apostrophes (e.g., export 'myfunc@8').
ΓòÉΓòÉΓòÉ 3.21. The FILE Directive ΓòÉΓòÉΓòÉ
Formats: All
The "FILE" directive is used to specify the object files and library modules
that the Watcom Linker is to process. The format of the "FILE" directive
(short form "F") is as follows.
FILE obj_spec{,obj_spec}
obj_spec ::= obj_file[(obj_module)]
| library_file[(obj_module)]
where
description
obj_file
is a file specification for the name of an object file. If no file
extension is specified, a file extension of "obj" is assumed if you are
running a DOS, OS/2 or Windows-hosted version of the Watcom Linker.
Also, if you are running a DOS, OS/2 or Windows-hosted version of the
Watcom Linker, the object file specification can contain wild cards (*,
?). A file extension of "o" is assumed if you are running a QNX-hosted
version of the Watcom Linker.
library_file
is a file specification for the name of a library file. Note that the
file extension of the library file (usually "lib") must be specified;
otherwise an object file will be assumed. When a library file is
specified, all object files in the library are included (whether required
or not).
obj_module
is the name of an object module defined in an object or library file.
Consider the following example.
Example:
wlink system my_os f \math\sin, mycos
The Watcom Linker is instructed to process the following object files:
\math\sin.obj
mycos.obj
The object file "mycos.obj" is located in the current directory since no path
was specified.
More than one "FILE" directive may be used. The following example is
equivalent to the preceding one.
Example:
wlink system my_os f \math\sin f mycos
Thus, other directives may be placed between lists of object files.
The "FILE" directive can also specify object modules from a library file or
object file. Consider the following example.
Example:
wlink system my_os f \math\math.lib(sin)
The Watcom Linker is instructed to process the object module "sin" contained
in the library file "math.lib" in the directory "\math".
In the following example, the Watcom Linker will process the object module
"sin" contained in the object file "math.obj" in the directory "\math".
Example:
wlink system my_os f \math\math(sin)
In the following example, the Watcom Linker will include all object modules
contained in the library file "math.lib" in the directory "\math".
Example:
wlink system my_os f \math\math.lib
ΓòÉΓòÉΓòÉ 3.22. The FORMAT Directive ΓòÉΓòÉΓòÉ
Formats: All
The "FORMAT" directive is used to specify the format of the executable file
that the Watcom Linker is to generate. The format of the "FORMAT" directive
(short form "FORM") is as follows.
FORMAT form
form ::= DOS [COM]
| WINDOWS [win_dll] [MEMORY] [FONT]
| WINDOWS NT [TNT] [dll_attrs]
| OS2 [os2_type] [dll_attrs | os2_attrs]
| PHARLAP [EXTENDED | REX | SEGMENTED]
| NOVELL [NLM | LAN | DSK | NAM] 'description'
| QNX [FLAT]
| ELF [DLL]
win_dll ::= DLL [INITGLOBAL | INITINSTANCE]
dll_attrs ::= DLL [INITGLOBAL | INITINSTANCE]
[TERMINSTANCE | TERMGLOBAL]
os2_type ::= FLAT | LE | LX
os2_attrs ::= PM | PMCOMPATIBLE | FULLSCREEN
| PHYSDEVICE | VIRTDEVICE
where
description
DOS
(short form "D") tells the Watcom Linker to generate a DOS "EXE" file.
The name of the executable file will have extension "exe". If "COM" is
specified, a DOS "COM" file will be generated in which case the name of
the executable file will have extension "com". Note that these default
extensions can be overridden by using the "NAME" directive to name the
executable file.
Not all programs can be generated in the "COM" format. The following
rules must be followed.
1. The program must consist of only one physical segment. This implies
that the size of the program (code and data) must be less than 64k.
2. The program must not contain any segment relocation. A warning
message will be issued by the Watcom Linker each time a segment
relocation is encountered.
A DOS "COM" file cannot contain debugging information. If you wish to
debug a DOS "COM" file, you must use the "SYMFILE" option to instruct the
Watcom Linker to place the debugging information in a separate file.
For more information on DOS executable file formats, see the chapter
entitled DOS: The DOS Executable File Format.
WINDOWS
tells the Watcom Linker to generate a Win16 (16-bit Windows) executable
file.
The name of the executable file will have extension "exe". If "DLL"
(short form "DL") is specified, a Dynamic Link Library will be generated;
the name of the executable file will also have extension "exe". Note
that these default extensions can be overridden by using the "NAME"
directive to name the executable file.
Specifying "INITGLOBAL" (short form "INITG") will cause Windows to call
an initialization routine the first time the Dynamic Link Library is
loaded. The "INITGLOBAL" option should be used with "OPTION ONEAUTODATA"
(the default for Dynamic Link Libraries). If the "INITGLOBAL" option is
used with "OPTION MANYAUTODATA", the initialization code will be called
once for the first data segment allocated but not for subsequent
allocations (this is generally not desirable behaviour and will likely
cause a program fault).
Specifying "INITINSTANCE" (short form "INITI") will cause Windows to call
an initialization routine each time the Dynamic Link Library is used by a
process. The "INITINSTANCE" option should be used with "OPTION
MANYAUTODATA" (the default for executable programs).
In either case, the initialization routine is defined by the start
address. If neither "INITGLOBAL" or "INITINSTANCE" is specified,
"INITGLOBAL" is assumed.
Specifying "MEMORY" (short form "MEM") indicates that the application
will run in standard or enhanced mode. If Windows 3.0 is running in
standard and enhanced mode, and "MEMORY" is not specified, a warning
message will be issued. The "MEMORY" specification was used in the
transition from Windows 2.0 to Windows 3.0. The "MEMORY" specification
is ignored in Windows 3.1 or later.
Specifying "FONT" (short form "FO") indicates that the
proportional-spaced system font can be used. Otherwise, the old-style
mono-spaced system font will be used. The "FONT" specification was used
in the transition from Windows 2.0 to Windows 3.0. The "FONT"
specification is ignored in Windows 3.1 or later.
For more information on Windows executable file formats, see the chapter
entitled Win16: The Win16 Executable and DLL File Formats.
WINDOWS NT
tells the Watcom Linker to generate a Win32 executable file ("PE"
format).
If "TNT" is specified, an executable for the Phar Lap TNT DOS extender is
created. A "PL" format (rather than "PE") executable is created so that
the Phar Lap TNT DOS extender will always run the application (including
under Windows NT).
If "DLL" (short form "DL") is specified, a Dynamic Link Library will be
generated in which case the name of the executable file will have
extension "dll". Note that these default extensions can be overridden by
using the "NAME" directive to name the executable file.
Specifying "INITGLOBAL" (short form "INITG") will cause the
initialization routine to be called the first time the Dynamic Link
Library is loaded.
Specifying "INITINSTANCE" (short form "INITI") will cause the
initialization routine to be called each time the Dynamic Link Library is
referenced by a process.
In either case, the initialization routine is defined by the start
address. If neither "INITGLOBAL" or "INITINSTANCE" is specified,
"INITGLOBAL" is assumed.
It is also possible to specify whether the initialization routine is to
be called at DLL termination or not. Specifying "TERMGLOBAL" (short form
"TERMG") will cause the initialization routine to be called when the last
instance of the Dynamic Link Library is terminated. Specifying
"TERMINSTANCE" (short form "TERMI") will cause the initialization routine
to be called each time an instance of the Dynamic Link Library is
terminated. Note that the initialization routine is passed an argument
indicating whether it is being called during DLL initialization or DLL
termination. If "INITINSTANCE" is used and no termination option is
specified, "TERMINSTANCE" is assumed. If "INITGLOBAL" is used and no
termination option is specified, "TERMGLOBAL" is assumed.
For more information on Windows NT executable file formats, see the
chapter entitled Win32: The Win32 Executable and DLL File Formats.
OS2
tells the Watcom Linker to generate an OS/2 executable file format.
The name of the executable file will have extension "exe". If "LE" is
specified, an early form of the OS/2 32-bit linear executable will be
generated. This executable file format is required by Tenberry
Software's DOS/4G and DOS/4GW DOS extenders.
In order to improve load time and minimize the size of the executable
file, the OS/2 32-bit linear executable file format was changed. If "LX"
or "FLAT" (short form "FL") is specified, the new form of the OS/2 32-bit
linear executable will be generated. This executable file format is
required by the FlashTek DOS extender and 32-bit OS/2 executables.
If "FLAT", "LX" or "LE" is not specified, an OS/2 16-bit executable will
be generated.
If "DLL" (short form "DL") is specified, a Dynamic Link Library will be
generated in which case the name of the executable file will have
extension "dll". Note that these default extensions can be overridden by
using the "NAME" directive to name the executable file.
Specifying "INITGLOBAL" (short form "INITG") will cause the
initialization routine to be called the first time the Dynamic Link
Library is loaded. The "INITGLOBAL" option should be used with "OPTION
ONEAUTODATA" (the default for Dynamic Link Libraries). If the
"INITGLOBAL" option is used with "OPTION MANYAUTODATA", the
initialization code will be called once for the first data segment
allocated but not for subsequent allocations (this is generally not
desirable behaviour and will likely cause a program fault).
Specifying "INITINSTANCE" (short form "INITI") will cause the
initialization routine to be called each time the Dynamic Link Library is
referenced by a process. The "INITINSTANCE" option should be used with
"OPTION MANYAUTODATA" (the default for executable programs).
In either case, the initialization routine is defined by the start
address. If neither "INITGLOBAL" or "INITINSTANCE" is specified,
"INITGLOBAL" is assumed.
For OS/2 32-bit linear executable files, it is also possible to specify
whether the initialization routine is to be called at DLL termination or
not. Specifying "TERMGLOBAL" (short form "TERMG") will cause the
initialization routine to be called when the last instance of the Dynamic
Link Library is terminated. Specifying "TERMINSTANCE" (short form
"TERMI") will cause the initialization routine to be called each time an
instance of the Dynamic Link Library is terminated. Note that the
initialization routine is passed an argument indicating whether it is
being called during DLL initialization or DLL termination. If
"INITINSTANCE" is used and no termination option is specified,
"TERMINSTANCE" is assumed. If "INITGLOBAL" is used and no termination
option is specified, "TERMGLOBAL" is assumed.
If "PM" is specified, a Presentation Manager application will be created.
The application uses the API provided by the Presentation Manager and
must be executed in the Presentation Manager environment.
lf "PMCOMPATIBLE" (short form "PMC") is specified, an application
compatible with Presentation Manager will be created. The application
can run inside the Presentation Manager or it can run in a separate
screen group. An application can be of this type if it uses the proper
subset of OS/2 video, keyboard, and mouse functions supported in the
Presentation Manager applications. This is the default.
If "FULLSCREEN" (short form "FULL") is specified, an OS/2 full screen
application will be created. The application will run in a separate
screen group from the Presentation Manager.
If "PHYSDEVICE" (short form "PHYS") is specified, the executable file is
marked as a physical device driver.
If "VIRTDEVICE" (short form "VIRT") is specified, the executable file is
marked as a virtual device driver.
For more information on OS/2 executable file formats, see the chapter
entitled OS/2: The OS/2 Executable and DLL File Formats.
PHARLAP
(short form "PHAR") tells the Watcom Linker to generate an executable
file that will run under Phar Lap's 386|DOS-Extender.
There are 4 forms of executable files: simple, extended, relocatable and
segmented. If "EXTENDED" (short form "EXT") is specified, an extended
form of the executable file with file extension "exp" will be generated.
If "REX" is specified, a relocatable executable file with file extension
"rex" will be generated. If "SEGMENTED" (short form "SEG") is specified,
a segmented executable file with file extension "exp" will be generated.
If neither "EXTENDED", "REX" or "SEGMENTED" is specified, a simple
executable file with file extension "exp" will be generated. Note that
the default file extensions can be overridden by using the "NAME"
directive to name the executable file.
The simple form is for flat model 386 applications. It is the only
format that can be loaded by earlier versions of 386|DOS-Extender
(earlier than 1.2).
The extended form is used for flat model applications that have been
linked in a way which requires a method of specifying more information
for 386|DOS-Extender than possible with the simple form.
The relocatable form is similar to the simple form. Unique to the
relocatable form is an offset relocation table. This allows the loader
to load the program at any location it chooses.
The segmented form is used for embedded system applications like Intel
RMX. These executables cannot be loaded by 386|DOS-Extender.
A simple form of the executable file is generated in all but the
following cases.
1. "EXTENDED" is specified in the "FORMAT" directive.
2. The "RUNTIME" directive is specified. Options specified by the
"RUNTIME" directive can only be specified in the extended form of
the executable file.
3. The "OFFSET" option is specified. The value specified in the
"OFFSET" option can only be specified in the extended form of the
executable file.
4. "REX" is specified in the "FORMAT" directive. In this case, the
relocatable form will be generated. You must not specify the
"RUNTIME" directive or the "OFFSET" option when generating the
relocatable form.
5. "SEGMENTED" is specified in the "FORMAT" directive. In this case,
the segmented form will be generated.
For more information on Phar Lap executable file formats, see the chapter
entitled Phar Lap: The Phar Lap Executable File Format.
NOVELL
(short form "NOV") tells the Watcom Linker to generate a NetWare 386
executable file, more commonly called a NetWare Loadable Module (NLM).
NLMs are further classified according to their function. The executable
file will have a file extension that depends on the class of the NLM
being generated. The following describes the classification of NLMs.
LAN
instructs the Watcom Linker to generate a LAN driver. A LAN
driver is a device driver for Local Area Network hardware. A
file extension of "lan" is used for the name of the executable
file.
DSK
instructs the Watcom Linker to generate a disk driver. A file
extension of "dsk" is used for the name of the executable file.
NAM
instructs the Watcom Linker to generate a file system
name-space support module. A file extension of "nam" is used
for the name of the executable file.
NLM
instructs the Watcom Linker to generate a utility or server
application. This is the default. A file extension of "nlm"
is used for the name of the executable file.
description
is a textual description of the program being linked.
For more information on NetWare 386 executable file formats, see the
chapter entitled NetWare: The NetWare 386 Executable File Format.
QNX
tells the Watcom Linker to generate a QNX executable file.
If "FLAT" (short form "FL") is specified, a 32-bit flat executable file
is generated.
Under QNX, no file extension is added to the executable file name.
Under other operating systems, the name of the executable file will have
the extension "qnx". Note that this default extension can be overridden
by using the "NAME" directive to name the executable file.
For more information on QNX executable file formats, see the chapter
entitled QNX: The QNX Executable File Format.
ELF
tells the Watcom Linker to generate an ELF format executable file.
ELF format DLLs can also be created.
For more information on ELF executable file formats, see the chapter
entitled ELF: The ELF Executable File Format.
If no "FORMAT" directive is specified, the executable file format will be
selected for each of the following host systems in the way described.
DOS
If 16-bit object files are encountered, a 16-bit DOS executable will be
created. If 32-bit object files are encountered, a 32-bit DOS/4G
executable will be created.
OS/2
If 16-bit object files are encountered, a 16-bit OS/2 executable will be
created. If 32-bit object files are encountered, a 32-bit OS/2
executable will be created.
QNX
If 16-bit object files are encountered, a 16-bit QNX executable will be
created. If 32-bit object files are encountered, a 32-bit QNX executable
will be created.
Windows NT
If 16-bit object files are encountered, a 16-bit Windows executable will
be created. If 32-bit object files are encountered, a 32-bit Win32
executable will be created.
Windows 95
If 16-bit object files are encountered, a 16-bit Windows executable will
be created. If 32-bit object files are encountered, a 32-bit Win32
executable will be created.
ΓòÉΓòÉΓòÉ 3.23. The HEAPSIZE Option ΓòÉΓòÉΓòÉ
Formats: OS/2, QNX, Win16, Win32
The "HEAPSIZE" option specifies the size of the heap required by the
application. The format of the "HEAPSIZE" option (short form "H") is as
follows.
OPTION HEAPSIZE=n
where
description
n
represents a value. The complete form of n is the following.
[0x]d{d}[k|m]
d represents a decimal digit. If 0x is specified, the string of digits
represents a hexadecimal number. If k is specified, the value is
multiplied by 1024. If m is specified, the value is multiplied by
1024*1024.
n specifies the size of the heap. The default heap size is 0 bytes. The
maximum value of n is 65536 (64K) for 16-bit applications and 4G for 32-bit
applications which is the maximum size of a physical segment. Actually, for a
particular application, the maximum value of n is 64K or 4G less the size of
group "DGROUP".
ΓòÉΓòÉΓòÉ 3.24. The HELP Option ΓòÉΓòÉΓòÉ
Formats: NetWare
The "HELP" option specifies the file name of an internationalized help file
whose language corresponds to the message file bound to this NLM.
The format of the "HELP" option (short form "HE") is as follows.
OPTION HELP=help_file
where
description
help_file
is the name of the help file.
ΓòÉΓòÉΓòÉ 3.25. The IMPFILE Option ΓòÉΓòÉΓòÉ
Formats: NetWare, OS/2, Win16, Win32
The "IMPFILE" option requests the linker to produce a Watcom Library Manager
command file that can be used to create an import library that corresponds to
the DLL that is being generated. This option is useful in situations where the
Watcom Linker cannot create an import library file when you have specified the
"IMPLIB" option (i.e., the linker fails to launch Watcom Library Manager).
The format of the "IMPFILE" option (short form "IMPF") is as follows.
OPTION IMPFILE[=imp_file]
where
description
imp_file
is a file specification for the name of the command file that can be used
to create the import library file using the Watcom Library Manager. If
no file extension is specified, no file extension is assumed.
By default, no command file is generated. Specifying this option causes the
linker to generate an import library command file. The import library command
file contains a list of the entry points in your DLL. When this command file
is processed by the Watcom Library Manager, an import library file will be
produced.
If no file name is specified, the import library command file will have a
default file extension of "lbc" and the same file name as the DLL file. Note
that the import library command file will be created in the same directory as
the DLL file. The DLL file path and name can be specified in the "NAME"
directive.
Alternatively, a library command file path and name can be specified. The
following directive instructs the linker to generate a import library command
file and call it "mylib.lcf" regardless of the name of the executable file.
option impfile=mylib.lcf
You can also specify a path and/or file extension when using the "IMPFILE="
form of the "IMPFILE" option.
ΓòÉΓòÉΓòÉ 3.26. The IMPLIB Option ΓòÉΓòÉΓòÉ
Formats: NetWare, OS/2, Win16, Win32
The "IMPLIB" option requests the linker to produce an import library that
corresponds to the DLL that is being generated. The format of the "IMPLIB"
option (short form "IMPL") is as follows.
OPTION IMPLIB[=imp_lib]
where
description
imp_lib
is a file specification for the name of the import library file. If no
file extension is specified, a file extension of "lib" is assumed.
By default, no library file is generated. Specifying this option causes the
Watcom Linker to generate an import library file. The import library file
contains a list of the entry points in your DLL.
If no file name is specified, the import library file will have a default file
extension of "lib" and the same file name as the DLL file. Note that the
import library file will be created in the same directory as the DLL file. The
DLL file path and name can be specified in the "NAME" directive.
Alternatively, a library file path and name can be specified. The following
directive instructs the linker to generate a library file and call it
"mylib.imp" regardless of the name of the executable file.
option implib=mylib.imp
You can also specify a path and/or file extension when using the "IMPLIB="
form of the "IMPLIB" option.
ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
Note: At present, the linker spawns the Watcom Library Manager to create the
import library file.
ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
ΓòÉΓòÉΓòÉ 3.27. The IMPORT Directive ΓòÉΓòÉΓòÉ
Formats: ELF, NetWare, OS/2, Win16, Win32
The "IMPORT" directive is used to tell the Watcom Linker what symbols are
defined externally in other executables.
ΓòÉΓòÉΓòÉ 3.27.1. IMPORT - OS/2, Win16, Win32 only ΓòÉΓòÉΓòÉ
The "IMPORT" directive describes a function that belongs to a Dynamic Link
Library. The format of the "IMPORT" directive (short form "IMP") is as
follows.
IMPORT import{,import}
import ::= internal_name module_name[.entry_name | ordinal]
where
description
internal_name
is the name the application used to call the function.
module_name
is the name of the Dynamic Link Library. Note that this need not be the
same as the file name of the executable file containing the Dynamic Link
Library. This name corresponds to the name specified by the "MODNAME"
option when the Dynamic Link Library was created.
entry_name
is the actual name of the function as defined in the Dynamic Link
Library.
ordinal
is the ordinal value of the function. The ordinal number is an alternate
method that can be used to reference a function in a Dynamic Link
Library.
Notes:
1. By default, the Watcom C and C++ compilers append an underscore ('_') to
all function names. This should be considered when specifying
internal_name and entry_name in an "IMPORT" directive.
2. If the name contains characters that are special to the linker then the
name may be placed inside apostrophes (e.g., import 'myfunc@8').
The preferred method to resolve references to Dynamic Link Libraries is
through the use of import libraries. See the sections entitled OS/2: Using a
Dynamic Link Library, Win16: Using a Dynamic Link Library, or Win32: Using a
Dynamic Link Library for more information on import libraries.
ΓòÉΓòÉΓòÉ 3.27.2. IMPORT - ELF only ΓòÉΓòÉΓòÉ
The "IMPORT" directive is used to tell the Watcom Linker what symbols are
defined externally in other executables. The format of the "IMPORT" directive
(short form "IMP") is as follows.
IMPORT external_name{,external_name}
where
description
external_name
is the name of the external symbol.
Notes:
1. By default, the Watcom C and C++ compilers append an underscore ('_') to
all function names. This should be considered when specifying
external_name in an "IMPORT" directive.
2. If the name contains characters that are special to the linker then the
name may be placed inside apostrophes (e.g., import 'myfunc@8').
ΓòÉΓòÉΓòÉ 3.27.3. IMPORT - Netware only ΓòÉΓòÉΓòÉ
The "IMPORT" directive is used to tell the Watcom Linker what symbols are
defined externally in other NLMs. The format of the "IMPORT" directive (short
form "IMP") is as follows.
IMPORT external_name{,external_name}
where
description
external_name
is the name of the external symbol.
Notes:
1. If the name contains characters that are special to the linker then the
name may be placed inside apostrophes (e.g., import 'myfunc@8').
If an NLM contains external symbols, the NLMs that define the external symbols
must be loaded before the NLM that references the external symbols is loaded.
ΓòÉΓòÉΓòÉ 3.28. The @ Directive ΓòÉΓòÉΓòÉ
The "@" directive instructs the Watcom Linker to process directives from an
alternate source. The format of the "@" directive is as follows.
@directive_var
or
@directive_file
where
description
directive_var
is the name of an environment variable. The directives specified by the
value of directive_var will be processed.
directive_file
is a file specification for the name of a linker directive file. A file
extension of "lnk" is assumed if no file extension is specified.
The environment variable approach to specifying linker directives allows you
to specify commonly used directives without having to specify them each time
you invoke the Watcom Linker. If the environment variable "wlink" is set as
in the following example,
set wlink=debug watcom all option map, verbose library math
wlink @wlink
then each time the Watcom Linker is invoked, full debugging information will
be generated, a verbose map file will be created, and the library file
"math.lib" will be searched for undefined references.
A linker directive file is useful, for example, when the linker input consists
of a large number of object files and you do not want to type their names on
the command line each time you link your program. Note that a linker
directive file can also include other linker directive files.
Let the file "memos.lnk" be a directive file containing the following lines.
system my_os
name memos
file memos
file actions
file read
file msg
file prompt
file memmgr
library \termio\screen
library \termio\keyboard
Win16 only:
We must also use the "EXPORT" directive to define the window function.
This is done using the following directive.
export window_function
Consider the following example.
Example:
wlink @memos
The Watcom Linker is instructed to process the contents of the directive file
"memos.lnk". The executable image file will be called "memos.exe". The
following object files will be loaded from the current directory.
memos.obj
actions.obj
read.obj
msg.obj
prompt.obj
memmgr.obj
If any unresolved symbol references remain after all object files have been
processed, the library files "screen.lib" and "keyboard.lib" in the directory
"\termio" will be searched (in the order listed).
Notes:
1. In the above example, we did not provide the file extension when the
directive file was specified. The Watcom Linker assumes a file extension
of "lnk" if none is present.
2. It is not necessary to list each object file and library with a separate
directive. The following linker directive file is equivalent.
system my_os
name memos
file memos,actions,read,msg,prompt,memmgr
library \termio\screen,\termio\keyboard
However, if you want to selectively specify what debugging information
should be included, the first style of directive file will be easier to
use. This is illustrated in the following sample directive file.
system my_os
name memos
debug watcom lines
file memos
debug watcom all
file actions
debug watcom lines
file read
file msg
file prompt
file memmgr
debug watcom
library \termio\screen
library \termio\keyboard
3. Information for a particular directive can span directive files. This is
illustrated in the following sample directive file.
system my_os
file memos, actions, read, msg, prompt, memmgr
file @dbgfiles
library \termio\screen
library \termio\keyboard
The directive file "dbgfiles.lnk" contains, for example, those object
files that are used for debugging purposes.
ΓòÉΓòÉΓòÉ 3.29. The INCREMENTAL Option ΓòÉΓòÉΓòÉ
Formats: ELF, OS/2, PharLap, QNX, Win16, Win32
The "INCREMENTAL" option can be used to enable incremental linking.
Incremental linking is a process whereby the linker attempts to modify the
existing executable file by changing only those portions for which new object
files are provided.
The format of the "INCREMENTAL" option (short form "INC") is as follows.
OPTION INCREMENTAL[=inc_file_name]
where
description
inc_file_name
is a file specification for the name of the incremental information file.
If no file extension is specified, a file extension of "ilk" is assumed.
This option engages the incremental linking feature of the linker. This
option must be one of the first options encountered in the list of directives
and options supplied to the linker. If the option is presented too late, the
linker will issue a diagnostic message.
By default, the incremental information file has the same name as the program
except with an "ilk" extension unless the "NAME" directive has not been seen
yet. If this is the case then the file is called __WLINK.ILK.
The linker's incremental linking technique is very resistant to changes in the
underlying object files - there are very few cases where an incremental
re-link is not possible. The options "ELIMINATE" and "VFREMOVAL" cannot be
used at the same time as incremental linking.
It is possible, over time, to accumulate unneeded functions in the executable
by using incremental linking. To guarantee an executable of minimum size, you
can cause a full relink by deleting the ".ilk" file or by not specifying the
"INCREMENTAL" option.
Do not use a post processor like the Watcom Resource Compiler on the
executable file since this will damage the data structures maintained by the
linker. Add resources to the executable file using the "RESOURCE" option
which is described in The RESOURCE Option.
ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
Note: Only Dwarf debugging information is supported with incremental
linking.
ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
ΓòÉΓòÉΓòÉ 3.30. The INTERNALRELOCS Option ΓòÉΓòÉΓòÉ
Formats: OS/2
The "INTERNALRELOCS" option is used with LX format executables under 32-bit
OS/2. By default, OS/2 executables do not contain internal relocation
information and OS/2 Dynamic Link Libraries do contain internal relocation
information. This option causes the Watcom Linker to include internal
relocation information in OS/2 LX format executables.
The format of the "INTERNALRELOCS" option (short form "INT") is as follows.
OPTION INTERNALRELOCS
ΓòÉΓòÉΓòÉ 3.31. The LANGUAGE Directive ΓòÉΓòÉΓòÉ
Formats: All
The "LANGUAGE" directive is used to specify the language in which strings in
the Watcom Linker directives are specified. The format of the "LANGUAGE"
directive (short form "LANG") is as follows.
LANGUAGE lang
lang ::= JAPANESE | CHINESE | KOREAN
JAPANESE
(short form "JA") specifies that strings are to be handled as if they
contained characters from the Japanese Double-Byte Character Set (DBCS).
CHINESE
(short form "CH") specifies that strings are to be handled as if they
contained characters from the Chinese Double-Byte Character Set (DBCS).
KOREAN
(short form "KO") specifies that strings are to be handled as if they
contained characters from the Korean Double-Byte Character Set (DBCS).
ΓòÉΓòÉΓòÉ 3.32. The LIBFILE Directive ΓòÉΓòÉΓòÉ
Formats: All
The "LIBFILE" directive is used to specify the object files that the Watcom
Linker is to process. The format of the "LIBFILE" directive (short form
"LIBF") is as follows.
LIBFILE obj_spec{,obj_spec}
obj_spec ::= obj_file | library_file
where
description
obj_file
is a file specification for the name of an object file. If no file
extension is specified, a file extension of "obj" is assumed if you are
running a DOS, OS/2 or Windows-hosted version of the Watcom Linker.
Also, if you are running a DOS, OS/2 or Windows-hosted version of the
Watcom Linker, the object file specification can contain wild cards (*,
?). A file extension of "o" is assumed if you are running a QNX-hosted
version of the Watcom Linker.
library_file
is a file specification for the name of a library file. Note that the
file extension of the library file (usually "lib") must be specified;
otherwise an object file will be assumed. When a library file is
specified, all object files in the library are included (whether required
or not).
The difference between the "LIBFILE" directive and the "FILE" directive is as
follows.
1. When searching for an object or library file specified in a "LIBFILE"
directive, the default directory will be searched first, followed by the
paths specified in the "LIBPATH" directive, and finally the paths
specified in the "LIB" environment variable. Note that if the object or
library file name contains a path, only the specified path will be
searched.
2. Object or library file names specified in a "LIBFILE" directive will not
be used to create the name of the executable file when no "NAME"
directive is specified.
Essentially, object files that appear in "LIBFILE" directives are viewed as
components of a library that have not been explicitly placed in a library
file.
Consider the following linker directive file.
libpath \libs
libfile mystart
path \objs
file file1, file2
The Watcom Linker is instructed to process the following object files:
\libs\mystart.obj
\objs\file1.obj
\objs\file2.obj
Note that the executable file will have file name "file1" and not "mystart".
ΓòÉΓòÉΓòÉ 3.33. The LIBPATH Directive ΓòÉΓòÉΓòÉ
Formats: All
The "LIBPATH" directive is used to specify the directories that are to be
searched for library files appearing in subsequent "LIBRARY" directives and
object files appearing in subsequent "LIBFILE" directives. The format of the
"LIBPATH" directive (short form "LIBP") is as follows.
LIBPATH [path_name{;path_name}]
where
description
path_name
is a path name.
Consider a directive file containing the following linker directives.
file test
libpath \math
library trig
libfile newsin
First, the Watcom Linker will process the object file "test.obj" from the
default directory. The object file "newsin.obj" will then be processed,
searching the default directory first. If "newsin.obj" is not in the default
directory, the "\math" directory will be searched. If any unresolved
references remain after processing the object files, the library file
"trig.lib" will be searched. If the file "trig.lib" does not exist in the
default directory, the "\math" directory will be searched.
It is also possible to specify a list of paths in a "LIBPATH" directive.
Consider the following example.
libpath \newmath;\math
library trig
When processing undefined references, the Watcom Linker will attempt to
process the library file "trig.lib" in the default directory. If "trig.lib"
does not exist in the default directory, the "\newmath" directory will be
searched. If "trig.lib" does not exist in the "\newmath" directory, the
"\math" directory will be searched.
If the name of a library file appearing in a "LIBRARY" directive or the the
name of an object file appearing in a "LIBFILE" directive contains a path
specification, only the specified path will be searched.
Note that
libpath path1
libpath path2
is equivalent to the following.
libpath path2;path1
ΓòÉΓòÉΓòÉ 3.34. The LIBRARY Directive ΓòÉΓòÉΓòÉ
Formats: All
The "LIBRARY" directive is used to specify the library files to be searched
when unresolved symbols remain after processing all specified input object
files. The format of the "LIBRARY" directive (short form "L") is as follows.
LIBRARY library_file{,library_file}
where
description
library_file
is a file specification for the name of a library file. If no file
extension is specified, a file extension of "lib" is assumed.
Consider the following example.
Example:
wlink system my_os file trig lib \math\trig, \cmplx\trig
The Watcom Linker is instructed to process the following object file:
trig.obj
If any unresolved symbol references remain after all object files have been
processed, the following library files will be searched:
\math\trig.lib
\cmplx\trig.lib
More than one "LIBRARY" directive may be used. The following example is
equivalent to the preceding one.
Example:
wlink system my_os f trig lib \math\trig lib \cmplx\trig
Thus other directives may be placed between lists of library files.
ΓòÉΓòÉΓòÉ 3.34.1. Searching for Libraries Specified in Environment Variables ΓòÉΓòÉΓòÉ
The "LIB" environment variable can be used to specify a list of paths that will
be searched for library files. The "LIB" environment variable can be set using
the "set" command as follows:
set lib=\graphics\lib;\utility
Consider the following "LIBRARY" directive and the above definition of the
"LIB" environment variable.
library \mylibs\util, graph
If undefined symbols remain after processing all object files specified in all
"FILE" directives, the Watcom Linker will resolve these references by searching
the following libraries in the specified order.
1. the library file "\mylibs\util.lib"
2. the library file "graph.lib" in the current directory
3. the library file "\graphics\lib\graph.lib"
4. the library file "\utility\graph.lib"
Notes:
1. If a library file specified in a "LIBRARY" directive contains an absolute
path specification, the Watcom Linker will not search any of the paths
specified in the "LIB" environment string for the library file. Under
QNX, an absolute path specification is one that begins the "/" character.
Under all other operating systems, an absolute path specification is one
that begins with a drive specification or the "\" character.
2. Once a library file has been found, no further elements of the "LIB"
environment variable are searched for other libraries of the same name.
That is, if the library file "\graphics\lib\graph.lib" exists, the
library file "\utility\graph.lib" will not be searched even though
unresolved references may remain.
ΓòÉΓòÉΓòÉ 3.34.2. Converting Libraries Created using Phar Lap 386|LIB ΓòÉΓòÉΓòÉ
Phar Lap's librarian, 386|LIB, creates libraries whose dictionary is a
different format from the one used by other librarians. For this reason,
linking an application using the Watcom Linker with libraries created using
386|LIB will not work. Library files created using 386|LIB must be converted
to the form recognized by the Watcom Linker. This is achieved by issuing the
following WLIB command.
wlib newlib +pharlib.lib
The library file "pharlib.lib" is a library created using 386|LIB. The library
file "newlib.lib" will be created so that the Watcom Linker can now process it.
ΓòÉΓòÉΓòÉ 3.35. The LINEARRELOCS Option ΓòÉΓòÉΓòÉ
Formats: QNX
The "LINEARRELOCS" option instructs the linker to generate offset fixups in
addition to the normal segment fixups. The offset fixups allow the system to
move pieces of code and data that were loaded at a particular offset within a
segment to another offset within the same segment.
The format of the "LINEARRELOCS" option (short form "LI") is as follows.
OPTION LINEARRELOCS
ΓòÉΓòÉΓòÉ 3.36. The LONGLIVED Option ΓòÉΓòÉΓòÉ
Formats: QNX
The "LONGLIVED" option specifies that the application being linked will reside
in memory, or be active, for a long period of time (e.g., background tasks).
The memory manager, knowing an application is "LONGLIVED", allocates memory for
the application so as to reduce fragmentation.
The format of the "LONGLIVED" option (short form "LO") is as follows.
OPTION LONGLIVED
ΓòÉΓòÉΓòÉ 3.37. The MANGLEDNAMES Option ΓòÉΓòÉΓòÉ
Formats: All
The "MANGLEDNAMES" option should only be used if you are developing a Watcom
C++ application. Due to the nature of C++, the Watcom C++ compiler generates
mangled names for symbols. A mangled name for a symbol includes the following.
1. symbol name
2. scoping information
3. typing information
This information is stored in a cryptic form with the symbol. When the linker
encounters a mangled name in an object file, it formats the above information
and produces this name in the map file.
If you would like the linker to produce the mangled name as it appeared in the
object file, specify the "MANGLEDNAMES" option.
The format of the "MANGLEDNAMES" option (short form "MANG") is as follows.
OPTION MANGLEDNAMES
ΓòÉΓòÉΓòÉ 3.38. The MANYAUTODATA Option ΓòÉΓòÉΓòÉ
Formats: OS/2, Win16
The "MANYAUTODATA" option specifies that a copy of the automatic data segment
(default data segment defined by the group "DGROUP"), for the program module or
Dynamic Link Library (DLL) being created, is made for each instance. The
format of the "MANYAUTODATA" option (short form "MANY") is as follows.
OPTION MANYAUTODATA
The default for a program module is "MANYAUTODATA" and for a Dynamic Link
Library is "ONEAUTODATA". If you do not want the data area of a DLL to be
shared across multiple applications, then you should specify "OPTION
MANYAUTODATA".
Win16:
Note, however, that this attribute is not supported by Windows 3.x for
16-bit DLLs.
You should also see the related section entitled The FORMAT Directive for
information on the "INITINSTANCE", "TERMINSTANCE", "INITGLOBAL", and
"TERMGLOBAL" DLL attributes.
ΓòÉΓòÉΓòÉ 3.39. The MAP Option ΓòÉΓòÉΓòÉ
Formats: All
The "MAP" option controls the generation of a map file. The format of the
"MAP" option (short form "M") is as follows.
OPTION MAP[=map_file]
where
description
map_file
is a file specification for the name of the map file. If no file
extension is specified, a file extension of "map" is assumed.
By default, no map file is generated. Specifying this option causes the
Watcom Linker to generate a map file. The map file is simply a memory map of
your program. That is, it specifies the relative location of all global
symbols in your program. The map file also contains the size of your program.
If no file name is specified, the map file will have a default file extension
of "map" and the same file name as the executable file. Note that the map
file will be created in the current directory even if the executable file name
specified in the "NAME" directive contains a path specification.
Alternatively, a file name can be specified. The following directive
instructs the linker to generate a map file and call it "myprog.map"
regardless of the name of the executable file.
option map=myprog
You can also specify a path and/or file extension when using the "MAP=" form
of the "MAP" option.
ΓòÉΓòÉΓòÉ 3.40. The MAXDATA Option ΓòÉΓòÉΓòÉ
Formats: PharLap
The format of the "MAXDATA" option (short form "MAXD") is as follows.
OPTION MAXDATA=n
where
description
n
represents a value. The complete form of n is the following.
[0x]d{d}[k|m]
d represents a decimal digit. If 0x is specified, the string of digits
represents a hexadecimal number. If k is specified, the value is
multiplied by 1024. If m is specified, the value is multiplied by
1024*1024.
n specifies the maximum number of bytes, in addition to the memory required by
executable image, that may be allocated by 386|DOS-Extender at the end of the
loaded executable image. No more than n bytes will be allocated.
If the "MAXDATA" option is not specified, a default value of hexadecimal
ffffffff is assumed. This means that 386|DOS-Extender will allocate all
available memory to the program at load time.
ΓòÉΓòÉΓòÉ 3.41. The MAXERRORS Option ΓòÉΓòÉΓòÉ
Formats: All
The "MAXERRORS" option can be used to set a limit on the number of error
messages generated by the linker. Note that this does not include warning
messages. When this limit is reached, the linker will issue a fatal error and
terminate.
The format of the "MAXERRORS" option (short form "MAXE") is as follows.
OPTION MAXERRORS=n
where
description
n
is the maximum number of error messages issued by the linker.
ΓòÉΓòÉΓòÉ 3.42. The MESSAGES Option ΓòÉΓòÉΓòÉ
Formats: NetWare
The "MESSAGES" option specifies the file name of an internationalized message
file that contains the default messages for the NLM. This is the name of the
default message file to load for NLMs that are enabled. Enabling allows the
same NLM to display messages in different languages by switching message files.
The format of the "MESSAGES" option (short form "MES") is as follows.
OPTION MESSAGES=msg_file
where
description
msg_file
is the name of the message file.
ΓòÉΓòÉΓòÉ 3.43. The MINDATA Option ΓòÉΓòÉΓòÉ
Formats: PharLap
The format of the "MINDATA" option (short form "MIND") is as follows.
OPTION MINDATA=n
where
description
n
represents a value. The complete form of n is the following.
[0x]d{d}[k|m]
d represents a decimal digit. If 0x is specified, the string of digits
represents a hexadecimal number. If k is specified, the value is
multiplied by 1024. If m is specified, the value is multiplied by
1024*1024.
n specifies the minimum number of bytes, in addition to the memory required by
executable image, that must be allocated by 386|DOS-Extender at the end of the
loaded executable image. If n bytes are not available, the program will not
be executed.
If the "MINDATA" option is not specified, a default value of zero is assumed.
This means that 386|DOS-Extender will load the program as long as there is
enough memory for the load image; no extra memory is required.
ΓòÉΓòÉΓòÉ 3.44. The MODNAME Option ΓòÉΓòÉΓòÉ
Formats: OS/2, Win16, Win32
The "MODNAME" option specifies a name to be given to the module being created.
The format of the "MODNAME" option (short form "MODN") is as follows.
OPTION MODNAME=module_name
where
description
module_name
is the name of a Dynamic Link Library.
Once a module has been loaded (whether it be a program module or a Dynamic
Link Library), mod_name is the name of the module known to the operating
system. If the "MODNAME" option is not used to specify a module name, the
default module name is the name of the executable file without the file
extension.
ΓòÉΓòÉΓòÉ 3.45. The MODFILE Directive ΓòÉΓòÉΓòÉ
Formats: All
The "MODFILE" directive instructs the linker that only the specified object
files have changed. The format of the "MODFILE" directive (short form "MODF")
is as follows.
MODFILE obj_file{,obj_file}
where
description
obj_file
is a file specification for the name of an object file. If no file
extension is specified, a file extension of "obj" is assumed if you are
running a DOS, OS/2 or Windows-hosted version of the Watcom Linker.
Also, if you are running a DOS, OS/2 or Windows-hosted version of the
Watcom Linker, the object file specification can contain wild cards (*,
?). A file extension of "o" is assumed if you are running a QNX-hosted
version of the Watcom Linker.
This directive is used only in concert with incremental linking. This
directive tells the linker that only the specified object files have changed.
When this option is specified, the linker will not check the dates on any of
the object files or libraries when incrementally linking.
ΓòÉΓòÉΓòÉ 3.46. The MODTRACE Directive ΓòÉΓòÉΓòÉ
Formats: All
The "MODTRACE" directive instructs the Watcom Linker to print a list of all
modules that reference the symbols defined in the specified modules. The
format of the "MODTRACE" directive (short form "MODT") is as follows.
MODTRACE module_name{,module_name}
where
description
module_name
is the name of an object module defined in an object or library file.
The information is displayed in the map file. Consider the following example.
Example:
wlink system my_os op map file test lib math modt trig
If the module "trig" defines the symbols "sin" and "cos", the Watcom Linker
will list, in the map file, all modules that reference the symbols "sin" and
"cos".
ΓòÉΓòÉΓòÉ 3.47. The MODULE Directive ΓòÉΓòÉΓòÉ
Formats: ELF, NetWare
The "MODULE" directive is used to specify the DLLs or NLMs to be loaded before
this executable is loaded. The format of the "MODULE" directive (short form
"MODU") is as follows.
MODULE module_name{,module_name}
where
description
module_name
is the file name of a DLL or NLM.
ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
WARNING! Versions 3.0 and 3.1 of the NetWare 386 operating system do not
support the automatic loading of modules specified in the "MODULE" directive.
You must load them manually.
ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
ΓòÉΓòÉΓòÉ 3.48. The MULTILOAD Option ΓòÉΓòÉΓòÉ
Formats: NetWare
The "MULTILOAD" option specifies that the module can be loaded more than once
by a "load" command. The format of the "MULTILOAD" option (short form
"MULTIL") is as follows.
OPTION MULTILOAD
If the "MULTILOAD" option is not specified, it will not be possible to load the
module more than once using the "load" command.
ΓòÉΓòÉΓòÉ 3.49. The NAME Directive ΓòÉΓòÉΓòÉ
Formats: All
The "NAME" directive is used to provide a name for the executable file
generated by the Watcom Linker. The format of the "NAME" directive (short form
"N") is as follows.
NAME exe_file
where
description
exe_file
is a file specification for the name of the executable file. Under QNX,
no file extension is appended. For all other operating systems, a file
extension suitable for the current executable file format is appended if
no file extension is specified.
Consider the following example.
Example:
wlink system my_os name myprog file test, test2, test3
The linker is instructed to generate an executable file called "myprog.exe" if
you are running a DOS, OS/2 or Windows-hosted version of the linker. If you
are running a QNX-hosted version of the linker, an executable file called
"myprog" will be generated.
Notes:
1. No file extension was given when the executable file name was specified.
The linker assumes a file extension that depends on the format of the
executable file being generated. If you are running a QNX-hosted version
of the linker, no file extension will be assumed. The section entitled
The FORMAT Directive describes the "FORMAT" directive and how the file
extension is chosen for each executable file format.
2. If no "NAME" directive is present, the executable file will have the file
name of the first object file processed by the linker. If the first
object file processed is called "test.obj" and no "NAME" directive is
specified, an executable file called "test.exe" will be generated if you
are running a DOS or OS/2-hosted version of the linker. If you are
running a QNX-hosted version of the linker, an executable file called
"test" will be generated.
ΓòÉΓòÉΓòÉ 3.50. The NAMELEN Option ΓòÉΓòÉΓòÉ
Formats: All
The "NAMELEN" option tells the Watcom Linker that all symbols must be uniquely
identified in the number of characters specified or less. If any symbol fails
to satisfy this condition, a warning message will be issued. The warning
message will state that a symbol has been defined more than once.
The format of the "NAMELEN" option (short form "NAMEL") is as follows.
OPTION NAMELEN=n
where
description
n
represents a value. The complete form of n is the following.
[0x]d{d}[k|m]
d represents a decimal digit. If 0x is specified, the string of digits
represents a hexadecimal number. If k is specified, the value is
multiplied by 1024. If m is specified, the value is multiplied by
1024*1024.
Some computer systems, for example, require that all global symbols be
uniquely identified in 8 characters. By specifying an appropriate value for
the "NAMELEN" option, you can ease the task of porting your application to
other computer systems.
ΓòÉΓòÉΓòÉ 3.51. The NEWFILES Option ΓòÉΓòÉΓòÉ
Formats: OS/2
The "NEWFILES" option specifies that the application uses the high-performance
file system. This option is applicable to 16-bit OS/2 applications only. The
format of the "NEWFILES" option (short form "NEWF") is as follows.
OPTION NEWFILES
ΓòÉΓòÉΓòÉ 3.52. The NEWSEGMENT Directive ΓòÉΓòÉΓòÉ
Formats: DOS, OS/2, QNX, Win16
This directive is intended for 16-bit segmented applications. By default, the
Watcom Linker automatically groups logical code segments into physical
segments. By default, these segments are 64K bytes in size. However, the
"PACKCODE" option can be used to specify a maximum size for all physical
segments that is smaller than 64K bytes.
The "NEWSEGMENT" directive provides an alternate method of grouping code
segments into physical segments. By placing this directive after a sequence of
"FILE" directives, all code segments appearing in object modules specified by
the sequence of "FILE" directives will be packed into a physical segment. Note
that the size of a physical segment may vary in size. The format of the
"NEWSEGMENT" directive (short form "NEW") is as follows.
NEWSEGMENT
Consider the following example.
file file1, file2, file3
newsegment
file file4
file file5
Code segments from file1, file2 and file3 will be grouped into one physical
segment. Code segments from file4 and file5 will be grouped into another
physical segment.
Note that code segments extracted from library files will be grouped into
physical segments as well. The size of these physical segments is determined
by the "PACKCODE" option and is 64k by default.
ΓòÉΓòÉΓòÉ 3.53. The NLMFLAGS Option ΓòÉΓòÉΓòÉ
Formats: NetWare
The "NLMFLAGS" option is used to set bits in the flags field of the header of
the Netware executable file. The format of the "NLMFLAGS" option (short form
"NLMF") is as follows.
OPTION NLMFLAGS=some_value
where
description
some_value
is an integer value that is OR'ed into the flags field of the header of
the Netware executable.
ΓòÉΓòÉΓòÉ 3.54. The NOAUTODATA Option ΓòÉΓòÉΓòÉ
Formats: OS/2, Win16
The "NOAUTODATA" option specifies that no automatic data segment (default data
segment defined by the group "DGROUP"), exists for the program module or
Dynamic Link Library being created. This option applies to 16-bit applications
only. The format of the "NOAUTODATA" option (short form "NOA") is as follows.
OPTION NOAUTODATA
ΓòÉΓòÉΓòÉ 3.55. The NODEFAULTLIBS Option ΓòÉΓòÉΓòÉ
Formats: All
Special object module records that specify default libraries are placed in
object files generated by Watcom compilers. These libraries reflect the memory
and floating-point model that a source file was compiled for and are
automatically searched by the Watcom Linker when unresolved symbols are
detected. These libraries can exist in the current directory, in one of the
paths specified in "LIBPATH" directives, or in one of the paths specified in
the LIB environment variable.
Note that all library files that appear in a "LIBRARY" directive are searched
before default libraries. The "NODEFAULTLIBS" option instructs the Watcom
Linker to ignore default libraries. That is, only libraries appearing in a
"LIBRARY" directive are searched.
The format of the "NODEFAULTLIBS" option (short form "NOD") is as follows.
OPTION NODEFAULTLIBS
ΓòÉΓòÉΓòÉ 3.56. The NORELOCS Option ΓòÉΓòÉΓòÉ
Formats: QNX, Win32
The "NORELOCS" option specifies that no relocation information is to be written
to the executable file. When the "NORELOCS" option is specified, the
executable file can only be run in protected mode and will not run in real
mode. In real mode, the relocation information is required; in protected mode,
the relocation information is not required unless your application is running
at privilege level 0.
The format of the "NORELOCS" option (short form "NOR") is as follows.
OPTION NORELOCS
where
description
NORELOCS
tells the Watcom Linker not to generate relocation information.
ΓòÉΓòÉΓòÉ 3.57. The NOSTDCALL Option ΓòÉΓòÉΓòÉ
Formats: Win32
The "NOSTDCALL" option specifies that the characters unique to the __stdcall
calling convention be trimmed from all of the symbols that are exported from
the DLL being created. The format of the "NOSTDCALL" option (short form
"NOSTDC") is as follows.
OPTION NOSTDCALL
Considering the following declarations.
Example:
short PASCAL __export Function1( short var1,
long varlong,
short var2 );
short PASCAL __export Function2( long varlong,
short var2 );
Under ordinary circumstances, these __stdcall symbols are mapped to
"_Function1@12" and "_Function2@8" respectively. The "@12" and "@8" reflect
the number of bytes in the argument list (short is passed as int). When the
"NOSTDCALL" option is specified, these symbols are stripped of the "_" and
"@xx" adornments. Thus they are exported from the DLL as "Function1" and
"Function2".
This option makes it easier to access functions exported from DLLs, especially
when using other software languages such as FORTRAN which do not add on the
__stdcall adornments.
ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
Note: Use the "IMPLIB" option to create an import library for the DLL which
can be used with software languages that add on the __stdcall adornments.
ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
ΓòÉΓòÉΓòÉ 3.58. The OBJALIGN Option ΓòÉΓòÉΓòÉ
Formats: Win32
The "OBJALIGN" option specifies the alignment for objects in the executable
file. The format of the "OBJALIGN" option (short form "OBJA") is as follows.
OPTION OBJALIGN=n
where
description
n
represents a value. The complete form of n is the following.
[0x]d{d}[k|m]
d represents a decimal digit. If 0x is specified, the string of digits
represents a hexadecimal number. If k is specified, the value is
multiplied by 1024. If m is specified, the value is multiplied by
1024*1024.
n must be a value that is a power of 2 and is between 512 bytes and 256
megabytes inclusive. The default is 64k.
ΓòÉΓòÉΓòÉ 3.59. The OLDLIBRARY Option ΓòÉΓòÉΓòÉ
Formats: OS/2, Win16, Win32
The "OLDLIBRARY" option is used to preserve the export ordinals for successive
versions of a Dynamic Link Library. This ensures that any application that
references functions in a Dynamic Link Library by ordinal will continue to
execute correctly. The format of the "OLDLIBRARY" option (short form "OLD") is
as follows.
OPTION OLDLIBRARY=dll_name
where
description
dll_name
is a file specification for the name of a Dynamic Link Library. If no
file extension is specified, a file extension of "DLL" is assumed.
Only the current directory or a specified directory will be searched for
Dynamic Link Libraries specified in the "OLDLIBRARY" option.
ΓòÉΓòÉΓòÉ 3.60. The OFFSET Option ΓòÉΓòÉΓòÉ
Formats: OS/2, PharLap, QNX, Win32
For OS/2 and Win32 applications, the "OFFSET" option specifies the preferred
base linear address at which the executable or DLL will be loaded.
For 32-bit PharLap and QNX applications, the "OFFSET" option specifies the
offset in the program's segment in which the first byte of code or data is
loaded.
ΓòÉΓòÉΓòÉ 3.60.1. OFFSET - OS/2, Win32 only ΓòÉΓòÉΓòÉ
The "OFFSET" option specifies the preferred base linear address at which the
executable or DLL will be loaded. The Watcom Linker will relocate the
application for the specified base linear address so that when it is loaded by
the operating system, no relocation will be required. This decreases the load
time of the application.
If the operating system is unable to load the application at the specified base
linear address, it will load it at a different location which will increase the
load time since a relocation phase must be performed.
The format of the "OFFSET" option (short form "OFF") is as follows.
OPTION OFFSET=n
where
description
n
represents a value. The complete form of n is the following.
[0x]d{d}[k|m]
d represents a decimal digit. If 0x is specified, the string of digits
represents a hexadecimal number. If k is specified, the value is
multiplied by 1024. If m is specified, the value is multiplied by
1024*1024.
The "OFFSET" option is used to specify the base linear address (in bytes) at
which the program is loaded and must be a multiple of 64K. The linker will
round the value up to a multiple of 64K if it is not already a multiple of
64K. The default base linear address is 64K for OS/2 executables and 4096K
for Win32 executables.
This option is most useful for improving the load time of DLLs, especially for
an application that uses multiple DLLs.
ΓòÉΓòÉΓòÉ 3.60.2. OFFSET - PharLap only ΓòÉΓòÉΓòÉ
The "OFFSET" option specifies the offset in the program's segment in which the
first byte of code or data is loaded. The format of the "OFFSET" option (short
form "OFF") is as follows.
OPTION OFFSET=n
where
description
n
represents a value. The complete form of n is the following.
[0x]d{d}[k|m]
d represents a decimal digit. If 0x is specified, the string of digits
represents a hexadecimal number. If k is specified, the value is
multiplied by 1024. If m is specified, the value is multiplied by
1024*1024.
n specifies the offset (in bytes) at which the program is loaded and must be a
multiple of 4K. The Watcom Linker will round the value up to a multiple of 4K
if it is not already a multiple of 4K.
It is possible to detect NULL pointer references by linking the program at an
offset which is a multiple of 4K. Usually an offset of 4K is sufficient.
Example:
option offset=4k
When the program is loaded by 386|DOS-Extender, the pages skipped by the
"OFFSET" option are not mapped. Any reference to an unmapped area (such as a
NULL pointer) will cause a page fault preventing the NULL reference from
corrupting the program.
ΓòÉΓòÉΓòÉ 3.60.3. OFFSET - QNX only ΓòÉΓòÉΓòÉ
The "OFFSET" option specifies the offset in the program's segment in which the
first byte of code or data is loaded. This option does not apply to 16-bit QNX
applications. The format of the "OFFSET" option (short form "OFF") is as
follows.
OPTION OFFSET=n
where
description
n
represents a value. The complete form of n is the following.
[0x]d{d}[k|m]
d represents a decimal digit. If 0x is specified, the string of digits
represents a hexadecimal number. If k is specified, the value is
multiplied by 1024. If m is specified, the value is multiplied by
1024*1024.
n specifies the offset (in bytes) at which the program is loaded and must be a
multiple of 4K. The Watcom Linker will round the value up to a multiple of 4K
if it is not already a multiple of 4K. The following describes a use of the
"OFFSET" option.
It is possible to detect NULL pointer references by linking the program at an
offset which is a multiple of 4K. Usually an offset of 4K is sufficient.
Example:
option offset=4k
When the program is loaded, the pages skipped by the "OFFSET" option are not
mapped. Any reference to an unmapped area (such as a NULL pointer) will cause
a page fault preventing the NULL reference from corrupting the program.
ΓòÉΓòÉΓòÉ 3.61. The ONEAUTODATA Option ΓòÉΓòÉΓòÉ
Formats: OS/2, Win16
The "ONEAUTODATA" option specifies that the automatic data segment (default
data segment defined by the group "DGROUP"), for the program module or Dynamic
Link Library (DLL) being created, will be shared by all instances. The format
of the "ONEAUTODATA" option (short form "ONE") is as follows.
OPTION ONEAUTODATA
The default for a Dynamic Link Library is "ONEAUTODATA" and for a program
module is "MANYAUTODATA". If you do not want the data area of a DLL to be
shared across multiple applications, then you should specify "OPTION
MANYAUTODATA".
Win16:
Note, however, that this attribute is not supported by Windows 3.x for
16-bit DLLs.
You should also see the related section entitled The FORMAT Directive for
information on the "INITINSTANCE", "TERMINSTANCE", "INITGLOBAL", and
"TERMGLOBAL" DLL attributes.
ΓòÉΓòÉΓòÉ 3.62. The OPTION Directive ΓòÉΓòÉΓòÉ
Formats: All
The "OPTION" directive is used to specify options to the Watcom Linker. The
format of the "OPTION" directive (short form "OP") is as follows.
OPTION option{,option}
where
description
option
is any of the linker options available for the executable format that is
being generated.
ΓòÉΓòÉΓòÉ 3.63. The OPTLIB Directive ΓòÉΓòÉΓòÉ
Formats: All
The "OPTLIB" directive is used to specify the library files to be searched when
unresolved symbols remain after processing all specified input object files.
The format of the "OPTLIB" directive (no short form) is as follows.
OPTLIB library_file{,library_file}
where
description
library_file
is a file specification for the name of a library file. If no file
extension is specified, a file extension of "lib" is assumed.
This directive is similar to the "LIBRARY" directive except that the linker
will not issue a warning message if the library file cannot be found.
Consider the following example.
Example:
wlink system my_os file trig optlib \math\trig, \cmplx\trig
The Watcom Linker is instructed to process the following object file:
trig.obj
If any unresolved symbol references remain after all object files have been
processed, the following library files will be searched:
\math\trig.lib
\cmplx\trig.lib
More than one "OPTLIB" directive may be used. The following example is
equivalent to the preceding one.
Example:
wlink system my_os f trig optlib \math\trig optlib \cmplx\trig
Thus other directives may be placed between lists of library files.
ΓòÉΓòÉΓòÉ 3.63.1. Searching for Optional Libraries Specified in Environment Variables ΓòÉΓòÉΓòÉ
The "LIB" environment variable can be used to specify a list of paths that will
be searched for library files. The "LIB" environment variable can be set using
the "set" command as follows:
set lib=\graphics\lib;\utility
Consider the following "OPTLIB" directive and the above definition of the "LIB"
environment variable.
optlib \mylibs\util, graph
If undefined symbols remain after processing all object files specified in all
"FILE" directives, the Watcom Linker will resolve these references by searching
the following libraries in the specified order.
1. the library file "\mylibs\util.lib"
2. the library file "graph.lib" in the current directory
3. the library file "\graphics\lib\graph.lib"
4. the library file "\utility\graph.lib"
Notes:
1. If a library file specified in a "OPTLIB" directive contains an absolute
path specification, the Watcom Linker will not search any of the paths
specified in the "LIB" environment string for the library file. On
QNX-hosted systems, an absolute path specification is one that begins the
"/" character. On all other hosts, an absolute path specification is one
that begins with a drive specification or the "\" character.
2. Once a library file has been found, no further elements of the "LIB"
environment variable are searched for other libraries of the same name.
That is, if the library file "\graphics\lib\graph.lib" exists, the
library file "\utility\graph.lib" will not be searched even though
unresolved references may remain.
ΓòÉΓòÉΓòÉ 3.64. The OSDOMAIN Option ΓòÉΓòÉΓòÉ
Formats: NetWare
The "OSDOMAIN" option is used when the application is to run in the operating
system domain (ring 0).
The format of the "OSDOMAIN" option (short form "OSD") is as follows.
OPTION OSDOMAIN
ΓòÉΓòÉΓòÉ 3.65. The PSEUDOPREEMPTION Option ΓòÉΓòÉΓòÉ
Formats: NetWare
The "PSEUDOPREEMPTION" option specifies that an additional set of system calls
will yield control to other processes. Multitasking in the NetWare 386
operating system is non-preemptive. That is, a process must give up control in
order for other processes to execute. Using the "PSEUDOPREEMPTION" option
increases the probability that all processes are given an equal amount of CPU
time.
The format of the "PSEUDOPREEMPTION" option (short form "PS") is as follows.
OPTION PSEUDOPREEMPTION
ΓòÉΓòÉΓòÉ 3.66. The OSNAME Option ΓòÉΓòÉΓòÉ
Formats: All
The "OSNAME" option can be used to set the name of the target operating system
of the executable file generated by the linker. The format of the "OSNAME"
option (short form "OSN") is as follows.
OPTION OSNAME='string'
where
description
string
is any sequence of characters.
The information specified by the "OSNAME" option will be displayed in the
creating a ? executable message. This is the last line of output produced by
the linker, provided the "QUIET" option is not specified. Consider the
following example.
option osname='SuperOS'
The last line of output produced by the linker will be as follows.
creating a SuperOS executable
Some executable formats have a stub executable file that is run under 16-bit
DOS. The message displayed by the default stub executable file will be
modified when the "OSNAME" option is used. The default stub executable
displays the following message:
OS/2:
this is an OS/2 executable
Win16:
this is a Windows executable
Win32:
this is a Windows NT executable
If the "OSNAME" option used in the previous example was specified, the default
stub executable would generate the following message.
this is a SuperOS executable
ΓòÉΓòÉΓòÉ 3.67. The PACKCODE Option ΓòÉΓòÉΓòÉ
Formats: DOS, OS/2, QNX, Win16
This option is intended for 16-bit segmented applications. By default, the
Watcom Linker automatically groups logical code segments into physical
segments. The "PACKCODE" option is used to specify the size of the physical
segment. The format of the "PACKCODE" option (short form "PACKC") is as
follows.
OPTION PACKCODE=n
where
description
n
represents a value. The complete form of n is the following.
[0x]d{d}[k|m]
d represents a decimal digit. If 0x is specified, the string of digits
represents a hexadecimal number. If k is specified, the value is
multiplied by 1024. If m is specified, the value is multiplied by
1024*1024.
n specifies the size of the physical segments into which code segments are
packed. The default value of n is 64K for 16-bit applications. Note that
this is also the maximum size of a physical segment. To suppress automatic
grouping of code segments, specify a value of 0 for n.
Notes:
1. Only adjacent segments are packed into a physical segment.
2. Segments belonging to the same group are packed in a physical segment.
Segments belonging to different groups are not packed into a physical
segment.
3. Segments with different attributes are not packed together unless they
are explicitly grouped.
ΓòÉΓòÉΓòÉ 3.68. The PACKDATA Option ΓòÉΓòÉΓòÉ
Formats: DOS, OS/2, QNX, Win16
This option is intended for 16-bit segmented applications. By default, the
Watcom Linker automatically groups logical far data segments into physical
segments. The "PACKDATA" option is used to specify the size of the physical
segment. The format of the "PACKDATA" option (short form "PACKD") is as
follows.
OPTION PACKDATA=n
where
description
n
represents a value. The complete form of n is the following.
[0x]d{d}[k|m]
d represents a decimal digit. If 0x is specified, the string of digits
represents a hexadecimal number. If k is specified, the value is
multiplied by 1024. If m is specified, the value is multiplied by
1024*1024.
n specifies the size of the physical segments into which far data segments are
packed. The default value of n is 64K for 16-bit applications. Note that
this is also the maximum size of a physical segment. To suppress automatic
grouping of far data segments, specify a value of 0 for n.
Notes:
1. Only adjacent segments are packed into a physical segment.
2. Segments belonging to the same group are packed in a physical segment.
Segments belonging to different groups are not packed into a physical
segment.
3. Segments with different attributes are not packed together unless they
are explicitly grouped.
ΓòÉΓòÉΓòÉ 3.69. The PATH Directive ΓòÉΓòÉΓòÉ
Formats: All
The "PATH" directive is used to specify the directories that are to be searched
for object files appearing in subsequent "FILE" directives. When the "PATH"
directive is specified, the current directory will no longer be searched unless
it appears in the "PATH" directive. The format of the "PATH" directive (short
form "P") is as follows.
PATH path_name{;path_name}
where
description
path_name
is a path name.
Consider a directive file containing the following linker directives.
path \math
file sin
path \stats
file mean, variance
It instructs the Watcom Linker to process the following object files:
\math\sin.obj
\stats\mean.obj
\stats\variance.obj
It is also possible to specify a list of paths in a "PATH" directive.
Consider the following example.
path \math;\stats
file sin
First, the linker will attempt to load the file "\math\sin.obj". If
unsuccessful, the linker will attempt to load the file "\stats\sin.obj".
It is possible to override the path specified in a "PATH" directive by
preceding the object file name in a "FILE" directive with an absolute path
specification. On QNX-hosted systems, an absolute path specification is one
that begins the "/" character. On all other hosts, an absolute path
specification is one that begins with a drive specification or the "\"
character.
path \math
file sin
path \stats
file mean, \mydir\variance
The above directive file instructs the linker to process the following object
files:
\math\sin.obj
\stats\mean.obj
\mydir\variance.obj
ΓòÉΓòÉΓòÉ 3.70. The PRIVILEGE Option ΓòÉΓòÉΓòÉ
Formats: QNX
The "PRIVILEGE" option specifies the privilege level (0, 1, 2 or 3) at which
the application will run. The format of the "PRIVILEGE" option (short form
"PRIV") is as follows.
OPTION PRIVILEGE=n
where
description
n
represents a value. The complete form of n is the following.
[0x]d{d}[k|m]
d represents a decimal digit. If 0x is specified, the string of digits
represents a hexadecimal number. If k is specified, the value is
multiplied by 1024. If m is specified, the value is multiplied by
1024*1024.
The default privilege level is 0.
ΓòÉΓòÉΓòÉ 3.71. The PROTMODE Option ΓòÉΓòÉΓòÉ
Formats: OS/2
The "PROTMODE" option specifies that the application will only run in protected
mode. This option applies to 16-bit OS/2 applications only. The format of the
"PROTMODE" option (short form "PROT") is as follows.
OPTION PROTMODE
ΓòÉΓòÉΓòÉ 3.72. The QUIET Option ΓòÉΓòÉΓòÉ
Formats: All
The "QUIET" option tells the Watcom Linker to suppress all informational
messages. Only warning, error and fatal messages will be issued. By default,
the Watcom Linker issues informational messages. The format of the "QUIET"
option (short form "Q") is as follows.
OPTION QUIET
ΓòÉΓòÉΓòÉ 3.73. The REDEFSOK Option ΓòÉΓòÉΓòÉ
Formats: All
The "REDEFSOK" option tells the Watcom Linker to ignore redefined symbols and
to generate an executable file anyway. By default, warning messages are
displayed and an executable file is generated if redefined symbols are present.
The format of the "REDEFSOK" option (short form "RED") is as follows.
OPTION REDEFSOK
The "NOREDEFSOK" option tells the Watcom Linker to treat redefined symbols as
an error and to not generate an executable file. By default, warning messages
are displayed and an executable file is generated if redefined symbols are
present.
The format of the "NOREDEFSOK" option (short form "NORED") is as follows.
OPTION NOREDEFSOK
ΓòÉΓòÉΓòÉ 3.74. The REENTRANT Option ΓòÉΓòÉΓòÉ
Formats: NetWare
The "REENTRANT" option specifies that the module is reentrant. That is, if an
NLM is LOADed twice, the actual code in the server's memory is reused. The
NLM's start procedure is called once for each LOAD. The format of the
"REENTRANT" option (short form "RE") is as follows.
OPTION REENTRANT
ΓòÉΓòÉΓòÉ 3.75. The REFERENCE Directive ΓòÉΓòÉΓòÉ
Formats: All
The "REFERENCE" directive is used to explicitly reference a symbol that is not
referenced by any object file processed by the linker. If any symbol appearing
in a "REFERENCE" directive is not resolved by the linker, an error message will
be issued for that symbol specifying that the symbol is undefined.
The "REFERENCE" directive can be used to force object files from libraries to
be linked with the application. Also note that a symbol appearing in a
"REFERENCE" directive will not be eliminated by dead code elimination. For
more information on dead code elimination, see the section entitled The
ELIMINATE Option.
The format of the "REFERENCE" directive (short form "REF") is as follows.
REFERENCE symbol_name{, symbol_name}
where
description
symbol_name
is the symbol for which a reference is made.
Consider the following example.
reference domino
The symbol domino will be searched for. The object module that defines this
symbol will be linked with the application. Note that the linker will also
attempt to resolve symbols referenced by this module.
ΓòÉΓòÉΓòÉ 3.76. The RESOURCE Option ΓòÉΓòÉΓòÉ
Formats: OS/2, QNX, Win16, Win32
For 16-bit OS/2 executable files and Win16 or Win32 executable files, the
"RESOURCE" option requests the linker to add the specified resource file to the
executable file being generated. For QNX executable files, the "RESOURCE"
option specifies the contents of the resource record.
ΓòÉΓòÉΓòÉ 3.76.1. RESOURCE - OS/2, Win16, Win32 only ΓòÉΓòÉΓòÉ
The "RESOURCE" option requests the linker to add the specified resource file to
the executable file that is being generated. The format of the "RESOURCE"
option (short form "RES") is as follows.
OPTION RESOURCE[=resource_file]
where
description
resource_file
is a file specification for the name of the resource file that is to be
added to the executable file. If no file extension is specified, a file
extension of "RES" is assumed for all but QNX format executables.
The "RESOURCE" option cannot be used for 32-bit OS/2 executables.
ΓòÉΓòÉΓòÉ 3.76.2. RESOURCE - QNX only ΓòÉΓòÉΓòÉ
The "RESOURCE" option specifies the contents of the resource record in QNX
executable files. The format of the "RESOURCE" option (short form "RES") is as
follows.
OPTION RESOURCE resource_info
resource_info ::= 'string' | =resource_file
where
description
resource_file
is a file specification for the name of the resource file. No file
extension is assumed.
string
is a sequence of characters which is placed in the resource record.
If a resource file is specified, the contents of the resource file are
included in the resource record.
The resource record contains, for example, help information and is displayed
when the following command is executed.
use <executable>
QNX also provides the usemsg utility to manipulate the resource record of an
executable file. Its use is recommended. This utility is described in the
QNX "Utilities Reference" manual.
ΓòÉΓòÉΓòÉ 3.77. The RUNTIME Directive ΓòÉΓòÉΓòÉ
Formats: PharLap, Win32
For Win32 applications, the "RUNTIME" directive specifies the environment under
which the application will run.
For PharLap applications, the "RUNTIME" directive describes information that is
used by 386|DOS-Extender to setup the environment for execution of the program.
ΓòÉΓòÉΓòÉ 3.77.1. RUNTIME - Win32 only ΓòÉΓòÉΓòÉ
The "RUNTIME" directive specifies the environment under which the application
will run. The format of the "RUNTIME" directive (short form "RU") is as
follows.
RUNTIME env[=major[.minor]]
env ::= NATIVE | WINDOWS | CONSOLE | POSIX | OS2 | DOSSTYLE
where
description
env=major.minor
Specifying a system version in the form "major" or "major.minor"
indicates the minimum operating system version required for the
application. For example, the following indicates that the application
requires Windows 95.
runtime windows=4.0
NATIVE
(short form "NAT") indicates that the application is a native Windows NT
application.
WINDOWS
(short form "WIN") indicates that the application is a Windows
application.
CONSOLE
(short form "CON") indicates that the application is a character-mode
(command line oriented) application.
POSIX
(short form "POS") indicates that the application uses the POSIX
subsystem available with Windows NT.
OS2
indicates that the application is a 16-bit OS/2 1.x application.
DOSSTYLE
(short form "DOS") indicates that the application is a Phar Lap TNT DOS
extender application that uses INT 21 to communicate to the DOS extender
rather than calls to a DLL.
ΓòÉΓòÉΓòÉ 3.77.2. RUNTIME - PharLap only ΓòÉΓòÉΓòÉ
The "RUNTIME" directive describes information that is used by 386|DOS-Extender
to setup the environment for execution of the program. The format of the
"RUNTIME" directive (short form "RU") is as follows.
RUNTIME run_option{,run_option}
run_option ::= MINREAL=n | MAXREAL=n | CALLBUFS=n | MINIBuf=n
| MAXIBUF=n | NISTACK=n | ISTKSIZE=n
| REALBREAK=offset | PRIVILEGED | UNPRIVILEGED
offset ::= n | symbol_name
where
description
n
represents a value. The complete form of n is the following.
[0x]d{d}[k|m]
d represents a decimal digit. If 0x is specified, the string of digits
represents a hexadecimal number. If k is specified, the value is
multiplied by 1024. If m is specified, the value is multiplied by
1024*1024.
symbol_name
is a symbol name.
MINREAL
(short form "MINR") specifies the minimum number of bytes of conventional
memory required to be free after a program is loaded by 386|DOS-Extender.
Note that this memory is no longer available to the executing program.
The default value of n is 0 in which case 386|DOS-Extender allocates all
conventional memory for the executing program. The Watcom Linker
truncates the specified value to a multiple of 16. n must be less than
or equal to hexadecimal 100000 (64K*16).
MAXREAL
(short form "MAXR") specifies the maximum number of bytes of conventional
memory than can be left free after a program is loaded by
386|DOS-Extender. Note that this memory is not available to the
executing program. The default value of n is 0 in which case
386|DOS-Extender allocates all conventional memory for the executing
program. n must be less than or equal to hexadecimal ffff0. The Watcom
Linker truncates the specified value to a multiple of 16.
CALLBUFS
(short form "CALLB") specifies the size of the call buffer allocated for
switching between 32-bit protected mode and real mode. This buffer is
used for communicating information between real-mode and 32-bit
protected-mode procedures. The buffer address is obtained at run-time
with a 386|DOS-Extender system call. The size returned is the size of
the buffer in kilobytes and is less than or equal to 64.
The default buffer size is zero unless changed using the "CALLBUFS"
option. The Watcom Linker truncates the specified value to a multiple of
1024. n must be less than or equal to 64K. Note that n is the number of
bytes, not kilobytes.
MINIBUF
(short form "MINIB") specifies the minimum size of the data buffer that
is used when DOS and BIOS functions are called. The size of this buffer
is particularly important for file I/O. If your program reads or writes
large amounts of data, a large value of n should be specified. n
represents the number of bytes and must be less than or equal to 64K.
The default value of n is 1K. The Watcom Linker truncates the specified
value to a multiple of 1024.
MAXIBUF
(short form "MAXIB") specifies the maximum size of the data buffer that
is used when DOS and BIOS functions are called. The size of this buffer
is particularly important for file I/O. If your program reads or writes
large amounts of data, a large value of n should be specified. n
represents the number of bytes and must be less than or equal to 64K.
The default value of n is 4K. The Watcom Linker truncates the specified
value to a multiple of 1024.
NISTACK
(short form "NIST") specifies the number of stack buffers to be allocated
for use by 386|DOS-Extender when switching from 32-bit protected mode to
real mode. By default, 4 stack buffers are allocated. n must be greater
than or equal to 4.
ISTKSIZE
(short form "ISTK") specifies the size of the stack buffers allocated for
use by 386|DOS-Extender when switching from 32-bit protected mode to real
mode. By default, the size of a stack buffer is 1K. The value of n must
be greater than or equal to 1K and less than or equal to 64K. The Watcom
Linker truncates the specified value to a multiple of 1024.
REALBREAK
(short form "REALB") specifies how much of the program must be loaded
into conventional memory so that it can be accessed and/or executed in
real mode. If n is specified, the first n bytes of the program must be
loaded into conventional memory. If symbol is specified, all bytes up to
but not including the symbol must be loaded into conventional memory.
PRIVILEGED
(short form "PRIV") specifies that the executable is to run at Ring 0
privilege level.
UNPRIVILEGED
(short form "UNPRIV") specifies that the executable is to run at Ring 3
privilege level (i.e., unprivileged). This is the default privilege
level.
ΓòÉΓòÉΓòÉ 3.78. The RWRELOCCHECK Option ΓòÉΓòÉΓòÉ
Formats: Win16
The "RWRELOCCHECK" option causes the linker to check for segment relocations to
a read/write data segment and issue a warning if any are found. This option is
useful if you are building a 16-bit Windows application that may have more than
one instance running at a given time.
The format of the "RWRELOCCHECK" option (short form "RWR") is as follows.
OPTION RWRELOCCHECK
ΓòÉΓòÉΓòÉ 3.79. The SCREENNAME Option ΓòÉΓòÉΓòÉ
Formats: NetWare
The "SCREENNAME" option specifies the name of the first screen (the screen that
is automatically created when an NLM is loaded). The format of the
"SCREENNAME" option (short form "SCR") is as follows.
OPTION SCREENNAME 'name'
where
description
name
specifies the screen name.
If the "SCREENNAME" option is not specified, the description text specified in
the "FORMAT" directive is used as the screen name.
ΓòÉΓòÉΓòÉ 3.80. The SEGMENT Directive ΓòÉΓòÉΓòÉ
Formats: OS/2, QNX, Win16, Win32
The "SEGMENT" directive is used to describe the attributes of code and data
segments. The format of the "SEGMENT" directive (short form "SEG") is as
follows.
SEGMENT seg_desc{,seg_desc}
seg_desc ::= seg_id {seg_attrs}+
seg_id ::= 'seg_name' | CLASS 'class_name' | TYPE [CODE | DATA]
OS/2:
seg_attrs ::= PRELOAD | LOADONCALL
| IOPL | NOIOPL
| EXECUTEONLY | EXECUTEREAD
| READONLY | READWRITE
| SHARED | NONSHARED
| CONFORMING | NONCONFORMING
| PERMANENT | NONPERMANENT
| INVALID | RESIDENT
| CONTIGUOUS | DYNAMIC
Win32:
seg_attrs ::= PAGEABLE | NONPAGEABLE
| SHARED | NONSHARED
Win16:
seg_attrs ::= PRELOAD | LOADONCALL
| EXECUTEONLY | EXECUTEREAD
| READONLY | READWRITE
| SHARED | NONSHARED
| MOVEABLE | FIXED
| DISCARDABLE
QNX:
seg_attrs ::= EXECUTEONLY | EXECUTEREAD
| READONLY | READWRITE
where
description
seg_name
is the name of the code or data segment whose attributes are being
specified.
class_name
is a class name. The attributes will be assigned to all segments
belonging to the specified class.
PRELOAD
(short form "PR", OS/2 and Win16 only) specifies that the segment is
loaded as soon as the executable file is loaded. This is the default.
LOADONCALL
(short form "LO", OS/2 and Win16 only) specifies that the segment is
loaded only when accessed.
PAGEABLE
(short form "PAGE", Win32 only) specifies that the segment can be paged
from memory. This is the default.
NONPAGEABLE
(short form "NONP", Win32 only) specifies that the segment, once loaded
into memory, must remain in memory.
CONFORMING
(short form "CON", OS/2 only) specifies that the segment will assume the
I/O privilege of the segment that referenced it. By default, the segment
is "NONCONFORMING".
NONCONFORMING
(short form "NONC", OS/2 only) specifies that the segment will not assume
the I/O privilege of the segment that referenced it. This is the
default.
IOPL
(short form "I", OS/2 only) specifies that the segment requires I/O
privilege. That is, they can access the hardware directly.
NOIOPL
(short form "NOI", OS/2 only) specifies that the segment does not require
I/O privilege. This is the default.
PERMANENT
(short form "PERM", OS/2 32-bit only) specifies that the segment is
permanent.
NONPERMANENT
(short form "NONPERM", OS/2 32-bit only) specifies that the segment is
not permanent.
INVALID
(short form "INV", OS/2 32-bit only) specifies that the segment is
invalid.
RESIDENT
(short form "RES", OS/2 32-bit only) specifies that the segment is
resident.
CONTIGUOUS
(short form "CONT", OS/2 32-bit only) specifies that the segment is
contiguous.
DYNAMIC
(short form "DYN", OS/2 32-bit only) specifies that the segment is
dynamic.
EXECUTEONLY
(short form "EXECUTEO", OS/2, QNX and Win16 only) specifies that the
segment can only be executed. This attribute should only be specified
for code segments. This attribute should not be specified if it is
possible for the code segment to contain jump tables which is the case
with the Watcom C, C++ and FORTRAN 77 optimizing compilers.
EXECUTEREAD
(short form "EXECUTER", OS/2, QNX and Win16 only) specifies that the
segment can only be executed and read. This attribute, the default for
code segments, should only be specified for code segments. This
attribute is appropriate for code segments that contain jump tables as is
possible with the Watcom C, C++ and FORTRAN 77 optimizing compilers.
READONLY
(short form "READO", OS/2, QNX and Win16 only) specifies that the segment
can only be read. This attribute should only be specified for data
segments.
READWRITE
(short form "READW", OS/2, QNX and Win16 only) specifies that the segment
can be read and written. This is the default for data segments. This
attribute should only be specified for data segments.
SHARED
(short form "SH" ) specifies that a single copy of the segment will be
loaded and will be shared by all processes.
NONSHARED
(short form "NONS") specifies that a unique copy of the segment will be
loaded for each process. This is the default.
MOVEABLE
(short form "MOV", Win16 only) specifies that the segment is moveable.
By default, segments are moveable.
FIXED
(short form "FIX", Win16 only) specifies that the segment is fixed.
DISCARDABLE
(short form "DIS", Win16 only) specifies that the segment is discardable.
By default, segments are not discardable.
ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
Note: Attributes specified for segments identified by a segment name
override attributes specified for segments identified by a class name.
ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
ΓòÉΓòÉΓòÉ 3.81. The SHARELIB Option ΓòÉΓòÉΓòÉ
Formats: NetWare
The "SHARELIB" option specifies the file name of an NLM to be loaded as a
shared NLM. Shared NLMs contain global code and global data that are mapped
into all memory protection domains. This method of loading APIs can be used to
avoid ring transitions to call other APIs in other domains.
The format of the "SHARELIB" option (short form "SHA") is as follows.
OPTION SHARELIB=shared_nlm
where
description
shared_nlm
is the file name of the shared NLM.
ΓòÉΓòÉΓòÉ 3.82. The SHOWDEAD Option ΓòÉΓòÉΓòÉ
Formats: All
The "SHOWDEAD" option instructs the linker to list, in the map file, the
symbols associated with dead code and unused C++ virtual functions that it has
eliminated from the link. The format of the "SHOWDEAD" option (short form
"SHO") is as follows.
OPTION SHOWDEAD
The "SHOWDEAD" option works best in concert with the "ELIMINATE" and
"VFREMOVAL" options.
ΓòÉΓòÉΓòÉ 3.83. The SORT Directive ΓòÉΓòÉΓòÉ
Formats: All
The "SORT" directive is used to sort the symbols in the "Memory Map" section of
the map file. By default, symbols are listed on a per module basis in the
order the modules were encountered by the linker. That is, a module header is
displayed followed by the symbols defined by the module.
The format of the "SORT" directive (short form "SO") is as follows.
SORT [GLOBAL] [ALPHABETICAL]
If the "SORT" directive is specified without any options, as in the following
example, the module headers will be displayed each followed by the list of
symbols it defines sorted by address.
sort
If only the "GLOBAL" sort option (short form "GL") is specified, as in the
following example, the module headers will not be displayed and all symbols
will be sorted by address.
sort global
If only the "ALPHABETICAL" sort option (short form "ALP") is specified, as in
the following example, the module headers will be displayed each followed by
the list of symbols it defines sorted alphabetically.
sort alphabetical
If both the "GLOBAL" and "ALPHABETICAL" sort options are specified, as in the
following example, the module headers will not be displayed and all symbols
will be sorted alphabetically.
sort global alphabetical
If you are linking a Watcom C++ application, mangled names are sorted by using
the base name. The base name is the name of the symbol as it appeared in the
source file. See the section entitled The MANGLEDNAMES Option for more
information on mangled names.
ΓòÉΓòÉΓòÉ 3.84. The STACK Option ΓòÉΓòÉΓòÉ
Formats: All
The "STACK" option can be used to increase the size of the stack. The format
of the "STACK" option (short form "ST") is as follows.
OPTION STACK=n
where
description
n
represents a value. The complete form of n is the following.
[0x]d{d}[k|m]
d represents a decimal digit. If 0x is specified, the string of digits
represents a hexadecimal number. If k is specified, the value is
multiplied by 1024. If m is specified, the value is multiplied by
1024*1024.
The default stack size varies for both 16-bit and protected-mode 32-bit
applications depending on the executable format. You can determine the
default stack size by looking at the map file that can be generated when an
application is linked ("OPTION MAP"). During execution of your program, you
may get an error message indicating your stack has overflowed. If you
encounter such an error, you must link your application again, this time
specifying a larger stack size using the "STACK" option.
Example:
option stack=8192
ΓòÉΓòÉΓòÉ 3.85. The START Option ΓòÉΓòÉΓòÉ
Formats: All
The format of the "START" option is as follows.
OPTION START=symbol_name
where
description
symbol_name
specifies the name of the procedure where execution begins.
For the Netware 386 executable format, the default name of the start procedure
is "_Prelude".
ΓòÉΓòÉΓòÉ 3.86. The STARTLINK Directive ΓòÉΓòÉΓòÉ
Formats: All
The "STARTLINK" directive is used to indicate the start of a new set of linker
commands that are to be processed after the current set of commands has been
processed. The format of the "STARTLINK" directive (short form "STARTL") is as
follows.
STARTLINK
The "ENDLINK" directive is used to indicate the end of the set of commands
identified by the "STARTLINK" directive.
ΓòÉΓòÉΓòÉ 3.87. The STATICS Option ΓòÉΓòÉΓòÉ
Formats: All
The "STATICS" option should only be used if you are developing a Watcom C or
C++ application. The Watcom C and C++ compilers produce definitions for static
symbols in the object file. By default, these static symbols do not appear in
the map file. If you want static symbols to be displayed in the map file, use
the "STATICS" option.
The format of the "STATICS" option (short form "STAT") is as follows.
OPTION STATICS
ΓòÉΓòÉΓòÉ 3.88. The STUB Option ΓòÉΓòÉΓòÉ
Formats: OS/2, Win16, Win32
The "STUB" option specifies an executable file containing a "stub" program that
is to be placed at the beginning of the executable file being generated. The
"stub" program will be executed if the module is executed under DOS. The
format of the "STUB" option is as follows.
OPTION STUB=stub_name
where
description
stub_name
is a file specification for the name of the stub executable file. If no
file extension is specified, a file extension of "EXE" is assumed.
The Watcom Linker will search all paths specified in the PATH environment
variable for the stub executable file. The stub executable file specified by
the "STUB" option must not be the same as the executable file being generated.
ΓòÉΓòÉΓòÉ 3.89. The SYMFILE Option ΓòÉΓòÉΓòÉ
Formats: All
The "SYMFILE" option provides a method for specifying an alternate file for
debugging information. The format of the "SYMFILE" option (short form "SYMF")
is as follows.
OPTION SYMFILE[=symbol_file]
where
description
symbol_file
is a file specification for the name of the symbol file. If no file
extension is specified, a file extension of "sym" is assumed.
By default, no symbol file is generated; debugging information is appended at
the end of the executable file. Specifying this option causes the Watcom
Linker to generate a symbol file. The symbol file contains the debugging
information generated by the linker when the "DEBUG" directive is used. The
symbol file can then be used by Watcom Debugger. If no debugging information
is requested, no symbol file is created, regardless of the presence of the
"SYMFILE" option.
If no file name is specified, the symbol file will have a default file
extension of "sym" and the same path and file name as the executable file.
Note that the symbol file will be placed in the same directory as the
executable file.
Alternatively, a file name can be specified. The following directive
instructs the linker to generate a symbol file and call it "myprog.sym"
regardless of the name of the executable file.
option symf=myprog
You can also specify a path and/or file extension when using the "SYMFILE="
form of the "SYMFILE" option.
Notes:
1. This option should be used to debug a DOS "COM" executable file. A DOS
"COM" executable file must not contain any additional information other
than the executable information itself since DOS uses the size of the
file to determine what to load.
2. This option should be used when creating a Microsoft Windows executable
file. Typically, before an executable file can be executed as a
Microsoft Windows application, a resource compiler takes the Windows
executable file and a resource file as input and combines them. If the
executable file contains debugging information, the resource compiler
will strip the debugging information from the executable file.
Therefore, debugging information must not be part of the executable file
created by the linker.
ΓòÉΓòÉΓòÉ 3.90. The SYMTRACE Directive ΓòÉΓòÉΓòÉ
Formats: All
The "SYMTRACE" directive instructs the Watcom Linker to print a list of all
modules that reference the specified symbols. The format of the "SYMTRACE"
directive (short form "SYMT") is as follows.
SYMTRACE symbol_name{,symbol_name}
where
description
symbol_name
is the name of a symbol.
The information is displayed in the map file. Consider the following example.
Example:
wlink system my_os op map file test lib math symt sin, cos
The Watcom Linker will list, in the map file, all modules that reference the
symbols "sin" and "cos".
ΓòÉΓòÉΓòÉ 3.91. The SYNCHRONIZE Option ΓòÉΓòÉΓòÉ
Formats: NetWare
The "SYNCHRONIZE" option forces an NLM to complete loading before starting to
load other NLMs. Normally, the other NLMs are loading during the startup
procedure. The format of the "SYNCHRONIZE" option (short form "SY") is as
follows.
OPTION SYNCHRONIZE
ΓòÉΓòÉΓòÉ 3.92. The SYSTEM Directive ΓòÉΓòÉΓòÉ
Formats: All
There are three forms of the "SYSTEM" directive.
The first form of the "SYSTEM" directive (short form "SYS") is called a system
definition directive. It allows you to associate a set of linker directives
with a specified name called the system name. This set of linker directives is
called a system definition block. The format of a system definition directive
is as follows.
SYSTEM BEGIN system_name {directive} END
where
description
system_name
is a unique system name.
directive
is a linker directive.
A system definition directive cannot be specified within another system
definition directive.
The second form of the "SYSTEM" directive is called a system deletion
directive. It allows you to remove the association of a set of linker
directives with a system name. The format of a system deletion directive is
as follows.
SYSTEM DELETE system_name
where
description
system_name
is a defined system name.
The third form of the "SYSTEM" directive is as follows.
SYSTEM system_name
where
description
system_name
is a defined system name.
When this form of the "SYSTEM" directive is encountered, all directives
specified in the system definition block identified by system_name will be
processed.
Let us consider an example that demonstrates the use of the "SYSTEM"
directive. The following linker directives define a system called statistics.
system begin statistics
format dos
libpath \libs
library stats, graphics
option stack=8k
end
They specify that a statistics application is to be created by using the
libraries "stats.lib" and "graphics.lib". These library files are located in
the directory "\libs". The application requires a stack size of 8k and the
specified format of executable will be generated.
Suppose the linker directives in the above example are contained in the file
"stats.lnk". If we wish to create a statistics application, we can issue the
following command.
wlink @stats system statistics file myappl
As demonstrated by the above example, the "SYSTEM" directive can be used to
localize the common attributes that describe a class of applications.
The system deletion directive can be used to redefine a previously defined
system. Consider the following example.
system begin at_dos
libpath %WATCOM%\lib286
libpath %WATCOM%\lib286\dos
format dos ^
end
system begin n98_dos
sys at_dos ^
libpath %WATCOM%\lib286\dos\n98
end
system begin dos
sys at_dos ^
end
If you wish to redefine the definition of the "dos" system, you can specify
the following set of directives.
system delete dos
system begin dos
sys n98_dos ^
end
This effectively redefines a "dos" system to be equivalent to a "n98_dos"
system (NEC PC-9800 DOS), rather than the previously defined "at_dos" system
(AT-compatible DOS).
For additional examples on the use of the "SYSTEM" directive, examine the
contents of the WLINK.LNK and WLSYSTEM.LNK files.
The file WLINK.LNK is a special linker directive file that is automatically
processed by the Watcom Linker before processing any other directives. On a
DOS, OS/2, or Windows-hosted system, this file must be located in one of the
paths specified in the PATH environment variable. On a QNX-hosted system,
this file should be located in the /etc directory. A default version of this
file is located in the \WATCOM\BINW directory on DOS-hosted systems, the
\WATCOM\BINP directory on OS/2-hosted systems, the /etc directory on
QNX-hosted systems, and the \WATCOM\BINNT directory on Windows 95 or Windows
NT-hosted systems. Note that the file WLINK.LNK includes the file
WLSYSTEM.LNK which is located in the \WATCOM\BINW directory on DOS, OS/2, or
Windows-hosted systems and the /etc directory on QNX-hosted systems.
The files WLINK.LNK and WLSYSTEM.LNK reference the WATCOM environment variable
which must be set to the directory in which you installed your software.
ΓòÉΓòÉΓòÉ 3.92.1. Special System Names ΓòÉΓòÉΓòÉ
There are two special system names. When the linker has processed all object
files and the executable file format has not been determined, and a system
definition block has not been processed, the directives specified in the "286"
or "386" system definition block will be processed. The "386" system
definition block will be processed if a 32-bit object file has been processed.
Furthermore, only a restricted set of linker directives is allowed in a "286"
and "386" system definition block. They are as follows.
FORMAT
LIBFILE
LIBPATH
LIBRARY
NAME
OPTION
RUNTIME (for Phar Lap executable files only)
SEGMENT (for OS/2 and QNX executable files only)
ΓòÉΓòÉΓòÉ 3.93. The THREADNAME Option ΓòÉΓòÉΓòÉ
Formats: NetWare
The "THREADNAME" option is used to specify the pattern to be used for
generating thread names. The format of the "THREADNAME" option (short form
"THR") is as follows.
OPTION THREADNAME 'thread_name'
where
description
thread_name
specifies the pattern used for generating thread names and must be a
string of 1 to 5 characters.
The first thread name is generated by appending "0" to thread_name, the second
by appending "1" to thread_name, etc. If the "THREADNAME" option is not
specified, the first 5 characters of the description specified in the "FORMAT"
directive are used as the pattern for generating thread names.
ΓòÉΓòÉΓòÉ 3.94. The TOGGLERELOCS Option ΓòÉΓòÉΓòÉ
Formats: OS/2
The "TOGGLERELOCS" option is used with LX format executables under 32-bit
DOS/4G only. The "INTERNALRELOCS" option causes the Watcom Linker to include
internal relocation information in DOS/4G LX format executables. Having done
so, the linker normally clears the "internal fixups done" flag in the LX
executable header (bit 0x10). The "TOGGLERELOCS" option causes the linker to
toggle the value of the "internal fixups done" flag in the LX executable header
(bit 0x10). This option is used with DOS/4G non-zero based executables.
Contact Tenberry Software for further explanation.
The format of the "TOGGLERELOCS" option (short form "TOG") is as follows.
OPTION TOGGLERELOCS
ΓòÉΓòÉΓòÉ 3.95. The UNDEFSOK Option ΓòÉΓòÉΓòÉ
Formats: All
The "UNDEFSOK" option tells the Watcom Linker to generate an executable file
even if undefined symbols are present. By default, no executable file will be
generated if undefined symbols are present.
The format of the "UNDEFSOK" option (short form "U") is as follows.
OPTION UNDEFSOK
The "NOUNDEFSOK" option tells the Watcom Linker to not generate an executable
file if undefined symbols are present. This is the default behaviour.
The format of the "NOUNDEFSOK" option (short form "NOU") is as follows.
OPTION NOUNDEFSOK
ΓòÉΓòÉΓòÉ 3.96. The VERBOSE Option ΓòÉΓòÉΓòÉ
Formats: All
The "VERBOSE" option controls the amount of information produced by the Watcom
Linker in the map file. The format of the "VERBOSE" option (short form "V") is
as follows.
OPTION VERBOSE
If the "VERBOSE" option is specified, the linker will list, for each object
file, all segments it defines and their sizes. By default, this information is
not produced in the map file.
ΓòÉΓòÉΓòÉ 3.97. The VERSION Option ΓòÉΓòÉΓòÉ
Formats: NetWare, OS/2, Win16, Win32
The "VERSION" option can be used to identify the application so that it can be
distinguished from other versions (releases) of the same application.
This option is most useful when creating a DLL or NLM since applications that
use the DLL or NLM may only execute with a specific version of the DLL or NLM.
The format of the "VERSION" option (short form "VERS") is as follows.
OS/2, Win16, Win32:
OPTION VERSION=major[.minor]
Netware:
OPTION VERSION=major[.minor[.revision]]
where
description
major
specifies the major version number.
minor
specifies the minor version number and must be less than 100.
revision
specifies the revision. The revision should be a number or a letter. If
it is a number, it must be less than 27.
ΓòÉΓòÉΓòÉ 3.98. The VFREMOVAL Option ΓòÉΓòÉΓòÉ
Formats: All
The "VFREMOVAL" option instructs the linker to remove unused C++ virtual
functions. The format of the "VFREMOVAL" option (short form "VFR") is as
follows.
OPTION VFREMOVAL
If the "VFREMOVAL" option is specified, the linker will attempt to eliminate
unused virtual functions. In order for the linker to do this, the Watcom C++
"zv" compiler option must be used for all object files in the executable. The
"VFREMOVAL" option works best in concert with the "ELIMINATE" option.
ΓòÉΓòÉΓòÉ 3.99. The XDCDATA Option ΓòÉΓòÉΓòÉ
Formats: NetWare
The "XDCDATA" option specifies the name of a file that contains Remote
Procedure Call (RPC) descriptions for calls in this NLM. RPC descriptions for
APIs make it possible for APIs to be exported across memory-protection domain
boundaries.
The format of the "XDCDATA" option (short form "XDC") is as follows.
OPTION XDCDATA=rpc_file
where
description
rpc_file
is the name of the file containing RPC descriptions.
ΓòÉΓòÉΓòÉ 4. DOS: The DOS Executable File Format ΓòÉΓòÉΓòÉ
This chapter deals specifically with aspects of DOS executable files. The DOS
executable file format will only run under the DOS operating system.
Input to the Watcom Linker is specified on the command line and can be
redirected to one or more files or environment strings. The Watcom Linker
command line format is as follows.
WLINK {directive}
where directive is any of the following:
ALIAS alias_name=symbol_name{,alias_name=symbol_name}
DEBUG dbtype [dblist] |
DISABLE msg_num{,msg_num}
ENDLINK
FILE obj_spec{,obj_spec}
FORMAT DOS [COM]
LANGUAGE lang
LIBFILE obj_file{,obj_file}
LIBPATH path_name{;path_name}
LIBRARY library_file{,library_file}
MODTRACE obj_module{,obj_module}
NAME exe_file
NEWSEGMENT
OPTION option{,option}
ARTIFICIAL
[NO]CACHE
[NO]CASEEXACT
CVPACK
DOSSEG
ELIMINATE
MANGLEDNAMES
MAP[=map_file]
MAXERRORS=n
NAMELEN=n
NODEFAULTLIBS
OSNAME='string'
PACKCODE=n
PACKDATA=n
QUIET
REDEFSOK
SHOWDEAD
STACK=n
START=symbol_name
STATICS
SYMFILE[=symbol_file]
[NO]UNDEFSOK
VERBOSE
VFREMOVAL
OPTLIB library_file{,library_file}
PATH path_name{;path_name}
REFERENCE symbol_name{,symbol_name}
SORT [GLOBAL] [ALPHABETICAL]
STARTLINK
SYMTRACE symbol_name{,symbol_name}
SYSTEM BEGIN system_name {directive} END
SYSTEM system_name
# comment
@ directive_file
You can view all the directives specific to DOS executable files by simply
typing the following:
wlink ? dos
Notes:
1. If the file "wlink.hlp" is located in one of the paths specified in the
"PATH" environment variable, the contents of that file will be displayed
when the following command is issued.
wlink ?
2. If all of the directive information does not fit on the command line,
type the following.
wlink
The prompt "WLINK>" will appear on the next line. You can enter as many
lines of directive information as required. Press "Ctrl/Z" followed by
the "Enter" key to terminate the input of directive information if you
are running a DOS, OS/2 or Windows NT-hosted version of the Watcom
Linker. Press "Ctrl/D" to terminate the input of directive information
if you are running a QNX-hosted version of the Watcom Linker.
ΓòÉΓòÉΓòÉ 4.1. DOS: Memory Layout ΓòÉΓòÉΓòÉ
The following describes the segment ordering of an application linked by the
Watcom Linker. Note that this assumes that the "DOSSEG" linker option has been
specified.
1. all segments not belonging to group "DGROUP" with class "CODE"
2. all other segments not belonging to group "DGROUP"
3. all segments belonging to group "DGROUP" with class "BEGDATA"
4. all segments belonging to group "DGROUP" not with class "BEGDATA", "BSS"
or "STACK"
5. all segments belonging to group "DGROUP" with class "BSS"
6. all segments belonging to group "DGROUP" with class "STACK"
A special segment belonging to class "BEGDATA" is defined when linking with
Watcom run-time libraries. This segment is initialized with the hexadecimal
byte pattern "01" and is the first segment in group "DGROUP" so that storing
data at location 0 can be detected.
Segments belonging to class "BSS" contain uninitialized data. Note that this
only includes uninitialized data in segments belonging to group "DGROUP".
Segments belonging to class "STACK" are used to define the size of the stack
used for your application. Segments belonging to the classes "BSS" and
"STACK" are last in the segment ordering so that uninitialized data need not
take space in the executable file.
ΓòÉΓòÉΓòÉ 4.2. DOS: The Watcom Linker Memory Requirements ΓòÉΓòÉΓòÉ
The Watcom Linker uses all available memory when linking an application. For
DOS-hosted versions of the Watcom Linker, this includes expanded memory (EMS)
and extended memory. It is possible for the size of the image being linked to
exceed the amount of memory available in your machine, particularly if the
image file is to contain debugging information. For this reason, a temporary
disk file is used when all available memory is used by the Watcom Linker.
Normally, the temporary file is created in the default directory. However, by
defining the "tmp" environment variable to be a directory, you can tell the
Watcom Linker where to create the temporary file. This can be particularly
useful if you have a RAM disk. Consider the following definition of the "tmp"
environment variable.
set tmp=\tmp
The Watcom Linker will create the temporary file in the directory "\tmp".
ΓòÉΓòÉΓòÉ 4.3. DOS: Using Overlays ΓòÉΓòÉΓòÉ
The creation of overlaid executables is not supported by this version of the
Watcom Linker.
ΓòÉΓòÉΓòÉ 4.4. DOS: Converting Microsoft Response Files to Directive Files ΓòÉΓòÉΓòÉ
A utility called MS2WLINK can be used to convert Microsoft linker response
files to Watcom Linker directive files. The response files must correspond to
the linker found in version 7 or earlier of Microsoft C. Later versions of
response files such as those used with Microsoft Visual C++ are not entirely
supported.
The same utility can also convert much of the content of IBM OS/2 LINK386
response files since the syntax is similar.
Input to MS2WLINK is processed in the same way as the Microsoft linker
processes its input. The difference is that MS2WLINK writes the corresponding
Watcom Linker directive file to the standard output device instead of a
creating an executable file. The resulting output can be redirected to a disk
file which can then be used as input to the Watcom Linker to produce an
executable file.
Suppose you have a Microsoft linker response file called "test.rsp". You can
convert this file to a Watcom Linker directive file by issuing the following
command.
Example:
ms2wlink @test.rsp >test.lnk
You can now use the Watcom Linker to link your program by issuing the following
command.
Example:
wlink @test
An alternative way to link your application with the Watcom Linker from a
Microsoft response file is to issue the following command.
Example:
ms2wlink @test.rsp | wlink
Since the Watcom Linker gets its input from the standard input device, you do
not have to create a Watcom Linker directive file to link your application.
Note that MS2WLINK can also process module-definition files used for creating
OS/2 applications.
ΓòÉΓòÉΓòÉ 5. ELF: The ELF Executable File Format ΓòÉΓòÉΓòÉ
This chapter deals specifically with aspects of ELF executable files. The ELF
executable file format will only run under the operating systems that support
the ELF executable file format.
Input to the Watcom Linker is specified on the command line and can be
redirected to one or more files or environment strings. The Watcom Linker
command line format is as follows.
WLINK {directive}
where directive is any of the following:
ALIAS alias_name=symbol_name{,alias_name=symbol_name}
DEBUG dbtype [dblist] |
DISABLE msg_num{,msg_num}
ENDLINK
EXPORT entry_name {,entry_name}
FILE obj_spec{,obj_spec}
FORMAT ELF [DLL]
IMPORT external_name {,external_name}
LANGUAGE lang
LIBFILE obj_file{,obj_file}
LIBPATH path_name{;path_name}
LIBRARY library_file{,library_file}
MODFILE obj_file{,obj_file}
MODTRACE obj_module{,obj_module}
MODULE module_name {,module_name}
NAME exe_file
OPTION option{,option}
ALIGNMENT=n
ARTIFICIAL
[NO]CACHE
[NO]CASEEXACT
CVPACK
DOSSEG
ELIMINATE
INCREMENTAL
MANGLEDNAMES
MAP[=map_file]
MAXERRORS=n
NAMELEN=n
NODEFAULTLIBS
OSNAME='string'
QUIET
REDEFSOK
SHOWDEAD
STACK=n
START=symbol_name
STATICS
SYMFILE[=symbol_file]
[NO]UNDEFSOK
VERBOSE
VFREMOVAL
OPTLIB library_file{,library_file}
PATH path_name{;path_name}
REFERENCE symbol_name{,symbol_name}
SORT [GLOBAL] [ALPHABETICAL]
STARTLINK
SYMTRACE symbol_name{,symbol_name}
SYSTEM BEGIN system_name {directive} END
SYSTEM system_name
# comment
@ directive_file
You can view all the directives specific to ELF executable files by simply
typing the following:
wlink ? elf
Notes:
1. If the file "wlink.hlp" is located in one of the paths specified in the
"PATH" environment variable, the contents of that file will be displayed
when the following command is issued.
wlink ?
2. If all of the directive information does not fit on the command line,
type the following.
wlink
The prompt "WLINK>" will appear on the next line. You can enter as many
lines of directive information as required. Press "Ctrl/Z" followed by
the "Enter" key to terminate the input of directive information if you
are running a DOS, OS/2 or Windows NT-hosted version of the Watcom
Linker. Press "Ctrl/D" to terminate the input of directive information
if you are running a QNX-hosted version of the Watcom Linker.
ΓòÉΓòÉΓòÉ 5.1. ELF: Memory Layout ΓòÉΓòÉΓòÉ
The following describes the segment ordering of an application linked by the
Watcom Linker. Note that this assumes that the "DOSSEG" linker option has been
specified.
1. all segments not belonging to group "DGROUP" with class "CODE"
2. all other segments not belonging to group "DGROUP"
3. all segments belonging to group "DGROUP" with class "BEGDATA"
4. all segments belonging to group "DGROUP" not with class "BEGDATA", "BSS"
or "STACK"
5. all segments belonging to group "DGROUP" with class "BSS"
6. all segments belonging to group "DGROUP" with class "STACK"
A special segment belonging to class "BEGDATA" is defined when linking with
Watcom run-time libraries. This segment is initialized with the hexadecimal
byte pattern "01" and is the first segment in group "DGROUP" so that storing
data at location 0 can be detected.
Segments belonging to class "BSS" contain uninitialized data. Note that this
only includes uninitialized data in segments belonging to group "DGROUP".
Segments belonging to class "STACK" are used to define the size of the stack
used for your application. Segments belonging to the classes "BSS" and
"STACK" are last in the segment ordering so that uninitialized data need not
take space in the executable file.
ΓòÉΓòÉΓòÉ 5.2. ELF: The Watcom Linker Memory Requirements ΓòÉΓòÉΓòÉ
The Watcom Linker uses all available memory when linking an application. For
DOS-hosted versions of the Watcom Linker, this includes expanded memory (EMS)
and extended memory. It is possible for the size of the image being linked to
exceed the amount of memory available in your machine, particularly if the
image file is to contain debugging information. For this reason, a temporary
disk file is used when all available memory is used by the Watcom Linker.
Normally, the temporary file is created in the default directory. However, by
defining the "tmp" environment variable to be a directory, you can tell the
Watcom Linker where to create the temporary file. This can be particularly
useful if you have a RAM disk. Consider the following definition of the "tmp"
environment variable.
set tmp=\tmp
The Watcom Linker will create the temporary file in the directory "\tmp".
ΓòÉΓòÉΓòÉ 6. NetWare: The NetWare 386 Executable File Format ΓòÉΓòÉΓòÉ
This chapter deals specifically with aspects of NetWare 386 executable files.
The Novell NetWare 386 executable file format will only run under the NetWare
386 operating system.
Input to the Watcom Linker is specified on the command line and can be
redirected to one or more files or environment strings. The Watcom Linker
command line format is as follows.
WLINK {directive}
where directive is any of the following:
ALIAS alias_name=symbol_name{,alias_name=symbol_name}
DEBUG dbtype [dblist] |
DISABLE msg_num{,msg_num}
ENDLINK
EXPORT entry_name {,entry_name}
FILE obj_spec{,obj_spec}
FORMAT NOVELL [NLM | LAN | DSK | NAM] 'description'
IMPORT external_name {,external_name}
LANGUAGE lang
LIBFILE obj_file{,obj_file}
LIBPATH path_name{;path_name}
LIBRARY library_file{,library_file}
MODTRACE obj_module{,obj_module}
MODULE module_name {,module_name}
NAME exe_file
OPTION option{,option}
ARTIFICIAL
[NO]CACHE
[NO]CASEEXACT
CHECK=symbol_name
COPYRIGHT 'string'
CUSTOM=file_name
CVPACK
DOSSEG
ELIMINATE
EXIT=symbol_name
HELP=help_file
IMPFILE[=imp_file]
IMPLIB[=imp_lib]
MANGLEDNAMES
MAP[=map_file]
MAXERRORS=n
MESSAGES=msg_file
MULTILOAD
NAMELEN=n
NLMFLAGS=some_value
NODEFAULTLIBS
OSDOMAIN
OSNAME='string'
PSEUDOPREEMPTION
QUIET
REDEFSOK
SHOWDEAD
REENTRANT
SCREENNAME 'name'
SHARELIB=shared_nlm
STACK=n
START=symbol_name
STATICS
SYMFILE[=symbol_file]
SYNCHRONIZE
THREADNAME 'thread_name'
[NO]UNDEFSOK
VERBOSE
VERSION=major[.minor[.revision]]
VFREMOVAL
XDCDATA=rpc_file
OPTLIB library_file{,library_file}
PATH path_name{;path_name}
REFERENCE symbol_name{,symbol_name}
SORT [GLOBAL] [ALPHABETICAL]
STARTLINK
SYMTRACE symbol_name{,symbol_name}
SYSTEM BEGIN system_name {directive} END
SYSTEM system_name
# comment
@ directive_file
You can view all the directives specific to NetWare 386 executable files by
simply typing the following:
wlink ? nov
Notes:
1. If the file "wlink.hlp" is located in one of the paths specified in the
"PATH" environment variable, the contents of that file will be displayed
when the following command is issued.
wlink ?
2. If all of the directive information does not fit on the command line,
type the following.
wlink
The prompt "WLINK>" will appear on the next line. You can enter as many
lines of directive information as required. Press "Ctrl/Z" followed by
the "Enter" key to terminate the input of directive information if you
are running a DOS, OS/2 or Windows NT-hosted version of the Watcom
Linker. Press "Ctrl/D" to terminate the input of directive information
if you are running a QNX-hosted version of the Watcom Linker.
ΓòÉΓòÉΓòÉ 6.1. NetWare: NetWare Loadable Modules ΓòÉΓòÉΓòÉ
NetWare Loadable Modules (NLMs) are executable files that run in file server
memory under the NetWare 386 operating system. NLMs can be loaded and unloaded
from file server memory while the server is running. When running they
actually become part of the operating system thus acting as building blocks for
a server environment tailored to your needs.
There are four types of NLMs, each identified by the file extension of the
executable file.
Utility and server applications (executable files with extension "nlm").
LAN drivers (executable files with extension "lan").
Disk drivers (executable files with extension "dsk").
Modules that define file system name spaces (executable files with
extension "nam").
The Watcom Linker can generate all four types of NLMs.
ΓòÉΓòÉΓòÉ 6.2. NetWare: Memory Layout ΓòÉΓòÉΓòÉ
The following describes the segment ordering of an application linked by the
Watcom Linker. Note that this assumes that the "DOSSEG" linker option has been
specified.
1. all segments not belonging to group "DGROUP" with class "CODE"
2. all other segments not belonging to group "DGROUP"
3. all segments belonging to group "DGROUP" with class "BEGDATA"
4. all segments belonging to group "DGROUP" not with class "BEGDATA", "BSS"
or "STACK"
5. all segments belonging to group "DGROUP" with class "BSS"
6. all segments belonging to group "DGROUP" with class "STACK"
A special segment belonging to class "BEGDATA" is defined when linking with
Watcom run-time libraries. This segment is initialized with the hexadecimal
byte pattern "01" and is the first segment in group "DGROUP" so that storing
data at location 0 can be detected.
Segments belonging to class "BSS" contain uninitialized data. Note that this
only includes uninitialized data in segments belonging to group "DGROUP".
Segments belonging to class "STACK" are used to define the size of the stack
used for your application. Segments belonging to the classes "BSS" and
"STACK" are last in the segment ordering so that uninitialized data need not
take space in the executable file.
ΓòÉΓòÉΓòÉ 6.3. NetWare: The Watcom Linker Memory Requirements ΓòÉΓòÉΓòÉ
The Watcom Linker uses all available memory when linking an application. For
DOS-hosted versions of the Watcom Linker, this includes expanded memory (EMS)
and extended memory. It is possible for the size of the image being linked to
exceed the amount of memory available in your machine, particularly if the
image file is to contain debugging information. For this reason, a temporary
disk file is used when all available memory is used by the Watcom Linker.
Normally, the temporary file is created in the default directory. However, by
defining the "tmp" environment variable to be a directory, you can tell the
Watcom Linker where to create the temporary file. This can be particularly
useful if you have a RAM disk. Consider the following definition of the "tmp"
environment variable.
set tmp=\tmp
The Watcom Linker will create the temporary file in the directory "\tmp".
ΓòÉΓòÉΓòÉ 7. OS/2: The OS/2 Executable and DLL File Formats ΓòÉΓòÉΓòÉ
This chapter deals specifically with aspects of OS/2 executable files. The
OS/2 16-bit executable file format will run under the following operating
systems.
1. 16-bit OS/2 1.x
2. 32-bit OS/2 2.x and 3.x (Warp)
3. Phar Lap's 286|DOS-Extender
The OS/2 32-bit linear executable file format will run under the following
operating systems.
1. OS/2 2.x (LX format only)
2. OS/2 3.x (LX format only)
3. Tenberry Software's DOS/4G and DOS/4GW DOS extenders (LE format only)
4. FlashTek's DOS Extender (LX format only)
Input to the Watcom Linker is specified on the command line and can be
redirected to one or more files or environment strings. The Watcom Linker
command line format is as follows.
WLINK {directive}
where directive is any of the following:
ALIAS alias_name=symbol_name{,alias_name=symbol_name}
DEBUG dbtype [dblist] |
DISABLE msg_num{,msg_num}
ENDLINK
EXPORT export{,export}
EXPORT =lbc_file
FILE obj_spec{,obj_spec}
FORMAT OS2 [exe_type] [dll_form | exe_attrs]
IMPORT import{,import}
LANGUAGE lang
LIBFILE obj_file{,obj_file}
LIBPATH path_name{;path_name}
LIBRARY library_file{,library_file}
MODFILE obj_file{,obj_file}
MODTRACE obj_module{,obj_module}
NAME exe_file
NEWSEGMENT
PATH path_name{;path_name}
OPTION option{,option}
ALIGNMENT=n
ARTIFICIAL
[NO]CACHE
[NO]CASEEXACT
CVPACK
DESCRIPTION 'string'
DOSSEG
ELIMINATE
HEAPSIZE=n
IMPFILE[=imp_file]
IMPLIB[=imp_lib]
INCREMENTAL
INTERNALRELOCS
MANGLEDNAMES
MANYAUTODATA
MAP[=map_file]
MAXERRORS=n
MODNAME=module_name
NAMELEN=n
NEWFILES
NOAUTODATA
NODEFAULTLIBS
OFFSET
OLDLIBRARY=dll_name
ONEAUTODATA
OSNAME='string'
PACKCODE=n
PACKDATA=n
PROTMODE
QUIET
REDEFSOK
RESOURCE=resource_file
SHOWDEAD
STACK=n
START=symbol_name
STATICS
STUB=stub_name
SYMFILE[=symbol_file]
TOGGLERELOCS
[NO]UNDEFSOK
VERBOSE
VERSION=major[.minor]
VFREMOVAL
OPTLIB library_file{,library_file}
REFERENCE symbol_name{,symbol_name}
SEGMENT seg_desc{,seg_desc}
SORT [GLOBAL] [ALPHABETICAL]
STARTLINK
SYMTRACE symbol_name{,symbol_name}
SYSTEM BEGIN system_name {directive} END
SYSTEM system_name
# comment
@ directive_file
You can view all the directives specific to OS/2 executable files by simply
typing the following:
wlink ? os2
Notes:
1. If the file "wlink.hlp" is located in one of the paths specified in the
"PATH" environment variable, the contents of that file will be displayed
when the following command is issued.
wlink ?
2. If all of the directive information does not fit on the command line,
type the following.
wlink
The prompt "WLINK>" will appear on the next line. You can enter as many
lines of directive information as required. Press "Ctrl/Z" followed by
the "Enter" key to terminate the input of directive information if you
are running a DOS, OS/2 or Windows NT-hosted version of the Watcom
Linker. Press "Ctrl/D" to terminate the input of directive information
if you are running a QNX-hosted version of the Watcom Linker.
ΓòÉΓòÉΓòÉ 7.1. OS/2: Dynamic Link Libraries ΓòÉΓòÉΓòÉ
The Watcom Linker can generate two forms of executable files; program modules
and Dynamic Link Libraries. A program module is the executable file that gets
loaded by the operating system when you run your application. A Dynamic Link
Library is really a library of routines that are called by a program module but
not linked into the program module. The executable code in a Dynamic Link
Library is loaded by the operating system during the execution of a program
module when a routine in the Dynamic Link Library is called.
Program modules are contained in files whose name has a file extension of
"exe". Dynamic Link Libraries are contained in files whose name has a file
extension of "dll". The Watcom Linker "FORMAT" directive can be used to select
the type of executable file to be generated.
Let us consider some of the advantages of using Dynamic Link Libraries over
standard libraries.
1. Functions in Dynamic Link Libraries are not linked into your program.
Only references to the functions in Dynamic Link Libraries are placed in
the program module. These references are called import definitions. As
a result, the linking time is reduced and disk space is saved. If many
applications reference the same Dynamic Link Library, the saving in disk
space can be significant.
2. Since program modules only reference Dynamic Link Libraries and do not
contain the actual executable code, a Dynamic Link Library can be updated
without re-linking your application. When your application is executed,
it will use the updated version of the Dynamic Link Library.
3. Dynamic Link Libraries also allow sharing of code and data between the
applications that use them. If many applications that use the same
Dynamic Link Library are executing concurrently, the sharing of code and
data segments improves memory utilization.
ΓòÉΓòÉΓòÉ 7.1.1. OS/2: Creating a Dynamic Link Library ΓòÉΓòÉΓòÉ
To create a Dynamic Link Library, you must place the "DLL" keyword following
the system name in the "SYSTEM" directive.
system system os2v2 dll
In addition, you must specify which functions in the Dynamic Link Library are
to be made available to applications which use it. This is achieved by using
the "EXPORT" directive for each function that can be called by an application.
Dynamic Link Libraries can reference other Dynamic Link Libraries. References
to other Dynamic Link Libraries are resolved by specifying "IMPORT" directives
or using import libraries.
ΓòÉΓòÉΓòÉ 7.1.2. OS/2: Using a Dynamic Link Library ΓòÉΓòÉΓòÉ
To use a Dynamic Link Library, you must tell the Watcom Linker which functions
are contained in a Dynamic Link Library and the name of the Dynamic Link
Library. This is achieved in two ways.
The first method is to use the "IMPORT" directive. The "IMPORT" directive
names the function and the Dynamic Link Library it belongs to so that the
Watcom Linker can generate an import definition in the program module.
The second method is to use import libraries. An import library is a standard
library which contains object modules with special object records that define
the functions belonging to a Dynamic Link Library. An import library is
created from a Dynamic Link Library using the Watcom Library Manager. The
resulting import library can then be specified in a "LIBRARY" directive in the
same way one would specify a standard library. See the chapter entitled "The
Watcom Library Manager" in the Watcom C/C++ Tools User's Guide or the Watcom
FORTRAN 77 Tools User's Guide for more information on creating import
libraries.
Using an import library is the preferred method of providing references to
functions in Dynamic Link Libraries. When a Dynamic Link Library is modified,
typically the import library corresponding to the modified Dynamic Link Library
is updated to reflect the changes. Hence, any directive file that specifies
the import library in a "LIBRARY" directive need not be modified. However, if
you are using "IMPORT" directives, you may have to modify the "IMPORT"
directives to reflect the changes in the Dynamic Link Library.
ΓòÉΓòÉΓòÉ 7.2. OS/2: Memory Layout ΓòÉΓòÉΓòÉ
The following describes the segment ordering of an application linked by the
Watcom Linker. Note that this assumes that the "DOSSEG" linker option has been
specified.
1. all segments not belonging to group "DGROUP" with class "CODE"
2. all other segments not belonging to group "DGROUP"
3. all segments belonging to group "DGROUP" with class "BEGDATA"
4. all segments belonging to group "DGROUP" not with class "BEGDATA", "BSS"
or "STACK"
5. all segments belonging to group "DGROUP" with class "BSS"
6. all segments belonging to group "DGROUP" with class "STACK"
A special segment belonging to class "BEGDATA" is defined when linking with
Watcom run-time libraries. This segment is initialized with the hexadecimal
byte pattern "01" and is the first segment in group "DGROUP" so that storing
data at location 0 can be detected.
Segments belonging to class "BSS" contain uninitialized data. Note that this
only includes uninitialized data in segments belonging to group "DGROUP".
Segments belonging to class "STACK" are used to define the size of the stack
used for your application. Segments belonging to the classes "BSS" and
"STACK" are last in the segment ordering so that uninitialized data need not
take space in the executable file.
ΓòÉΓòÉΓòÉ 7.3. OS/2: The Watcom Linker Memory Requirements ΓòÉΓòÉΓòÉ
The Watcom Linker uses all available memory when linking an application. For
DOS-hosted versions of the Watcom Linker, this includes expanded memory (EMS)
and extended memory. It is possible for the size of the image being linked to
exceed the amount of memory available in your machine, particularly if the
image file is to contain debugging information. For this reason, a temporary
disk file is used when all available memory is used by the Watcom Linker.
Normally, the temporary file is created in the default directory. However, by
defining the "tmp" environment variable to be a directory, you can tell the
Watcom Linker where to create the temporary file. This can be particularly
useful if you have a RAM disk. Consider the following definition of the "tmp"
environment variable.
set tmp=\tmp
The Watcom Linker will create the temporary file in the directory "\tmp".
ΓòÉΓòÉΓòÉ 7.4. OS/2: Converting Microsoft Response Files to Directive Files ΓòÉΓòÉΓòÉ
A utility called MS2WLINK can be used to convert Microsoft linker response
files to Watcom Linker directive files. The response files must correspond to
the linker found in version 7 or earlier of Microsoft C. Later versions of
response files such as those used with Microsoft Visual C++ are not entirely
supported.
The same utility can also convert much of the content of IBM OS/2 LINK386
response files since the syntax is similar.
Input to MS2WLINK is processed in the same way as the Microsoft linker
processes its input. The difference is that MS2WLINK writes the corresponding
Watcom Linker directive file to the standard output device instead of a
creating an executable file. The resulting output can be redirected to a disk
file which can then be used as input to the Watcom Linker to produce an
executable file.
Suppose you have a Microsoft linker response file called "test.rsp". You can
convert this file to a Watcom Linker directive file by issuing the following
command.
Example:
ms2wlink @test.rsp >test.lnk
You can now use the Watcom Linker to link your program by issuing the following
command.
Example:
wlink @test
An alternative way to link your application with the Watcom Linker from a
Microsoft response file is to issue the following command.
Example:
ms2wlink @test.rsp | wlink
Since the Watcom Linker gets its input from the standard input device, you do
not have to create a Watcom Linker directive file to link your application.
Note that MS2WLINK can also process module-definition files used for creating
OS/2 applications.
ΓòÉΓòÉΓòÉ 8. Phar Lap: The Phar Lap Executable File Format ΓòÉΓòÉΓòÉ
This chapter deals specifically with aspects of Phar Lap 386|DOS-Extender
executable files. The Phar Lap executable file format will run under the
following operating systems.
1. Phar Lap's 386|DOS-Extender
2. Watcom's 32-bit Windows supervisor (relocatable format only)
Input to the Watcom Linker is specified on the command line and can be
redirected to one or more files or environment strings. The Watcom Linker
command line format is as follows.
WLINK {directive}
where directive is any of the following:
ALIAS alias_name=symbol_name{,alias_name=symbol_name}
DEBUG dbtype [dblist] |
DISABLE msg_num{,msg_num}
ENDLINK
FILE obj_spec{,obj_spec}
FORMAT PHARLAP [EXTENDED | REX | SEGMENTED]
LANGUAGE lang
LIBFILE obj_file{,obj_file}
LIBPATH path_name{;path_name}
LIBRARY library_file{,library_file}
MODFILE obj_file{,obj_file}
MODTRACE obj_module{,obj_module}
NAME exe_file
OPTION option{,option}
ARTIFICIAL
[NO]CACHE
[NO]CASEEXACT
CVPACK
DOSSEG
ELIMINATE
INCREMENTAL
MANGLEDNAMES
MAP[=map_file]
MAXDATA=n
MAXERRORS=n
MINDATA=n
NAMELEN=n
NODEFAULTLIBS
OFFSET=n
OSNAME='string'
QUIET
REDEFSOK
SHOWDEAD
STACK=n
START=symbol_name
STATICS
SYMFILE[=symbol_file]
[NO]UNDEFSOK
VERBOSE
VFREMOVAL
OPTLIB library_file{,library_file}
PATH path_name{;path_name}
REFERENCE symbol_name{,symbol_name}
RUNTIME run_option{,run_option}
SORT [GLOBAL] [ALPHABETICAL]
STARTLINK
SYMTRACE symbol_name{,symbol_name}
SYSTEM BEGIN system_name {directive} END
SYSTEM system_name
# comment
@ directive_file
You can view all the directives specific to Phar Lap 386|DOS-Extender
executable files by simply typing the following:
wlink ? phar
Notes:
1. If the file "wlink.hlp" is located in one of the paths specified in the
"PATH" environment variable, the contents of that file will be displayed
when the following command is issued.
wlink ?
2. If all of the directive information does not fit on the command line,
type the following.
wlink
The prompt "WLINK>" will appear on the next line. You can enter as many
lines of directive information as required. Press "Ctrl/Z" followed by
the "Enter" key to terminate the input of directive information if you
are running a DOS, OS/2 or Windows NT-hosted version of the Watcom
Linker. Press "Ctrl/D" to terminate the input of directive information
if you are running a QNX-hosted version of the Watcom Linker.
ΓòÉΓòÉΓòÉ 8.1. Phar Lap: 32-bit Protected-Mode Applications ΓòÉΓòÉΓòÉ
The Watcom Linker generates executable files that run under Phar Lap's
386|DOS-Extender. 386|DOS-Extender provides a 32-bit protected-mode
environment for programs running under PC DOS. Running in 32-bit protected
mode allows your program to access all of the memory in your machine.
Essentially, what 386|DOS-Extender does is provide an interface between your
application and DOS running in real mode. Whenever your program issues a
software interrupt (DOS and BIOS system calls), 386|DOS-Extender intercepts the
requests, transfers data between the protected-mode and real-mode address
space, and calls the corresponding DOS system function running in real mode.
ΓòÉΓòÉΓòÉ 8.2. Phar Lap: Memory Usage ΓòÉΓòÉΓòÉ
When running a program under 386|DOS-Extender, memory for the program is
allocated from conventional memory (memory below one megabyte) and extended
memory. Conventional memory is allocated from a block of memory that is
obtained from DOS by 386|DOS-Extender at initialization time. By default, all
available memory is allocated at initialization time; no conventional memory
remains free. The "MINREAL" and "MAXREAL" options of the "RUNTIME" directive
control the amount of conventional memory initially left free by
386|DOS-Extender.
Part of the conventional memory allocated at initialization is required by
386|DOS-Extender. The following is allocated from conventional memory for use
by 386|DOS-Extender.
1. A data buffer is allocated and is used to pass data to DOS and BIOS
system functions. The size allocated is controlled by the "MINIBUF" and
"MAXIBUF" options of the "RUNTIME" directive.
2. Stack space is allocated and is used for switching between 32-bit
protected mode and real mode. The size allocated is controlled by the
"NISTACK" and "ISTKSIZE" options of the "RUNTIME" directive.
3. A call buffer is allocated and is used for passing data on function calls
between 32-bit protected mode and real mode. The size allocated is
controlled by the "CALLBUFS" option of the "RUNTIME" directive.
When a program is loaded by 386|DOS-Extender, memory to hold the entire
program is allocated. In addition, memory beyond the end of the program is
allocated for use by the program. By default, all extra memory is allocated
when the program is loaded. It is assumed that any memory not required by the
program is freed by the program. The amount of memory allocated at the end of
the program is controlled by the "MINDATA" and "MAXDATA" options.
ΓòÉΓòÉΓòÉ 8.3. Phar Lap: Memory Layout ΓòÉΓòÉΓòÉ
The following describes the segment ordering of an application linked by the
Watcom Linker. Note that this assumes that the "DOSSEG" linker option has been
specified.
1. all "USE16" segments. These segments are present in applications that
execute in both real mode and protected mode. They are first in the
segment ordering so that the "REALBREAK" option of the "RUNTIME"
directive can be used to separate the real-mode part of the application
from the protected-mode part of the application. Currently, the
"RUNTIME" directive is valid for Phar Lap executables only.
2. all segments not belonging to group "DGROUP" with class "CODE"
3. all other segments not belonging to group "DGROUP"
4. all segments belonging to group "DGROUP" with class "BEGDATA"
5. all segments belonging to group "DGROUP" not with class "BEGDATA", "BSS"
or "STACK"
6. all segments belonging to group "DGROUP" with class "BSS"
7. all segments belonging to group "DGROUP" with class "STACK"
Segments belonging to class "BSS" contain uninitialized data. Note that this
only includes uninitialized data in segments belonging to group "DGROUP".
Segments belonging to class "STACK" are used to define the size of the stack
used for your application. Segments belonging to the classes "BSS" and
"STACK" are last in the segment ordering so that uninitialized data need not
take space in the executable file.
ΓòÉΓòÉΓòÉ 8.4. Phar Lap: The Watcom Linker Memory Requirements ΓòÉΓòÉΓòÉ
The Watcom Linker uses all available memory when linking an application. For
DOS-hosted versions of the Watcom Linker, this includes expanded memory (EMS)
and extended memory. It is possible for the size of the image being linked to
exceed the amount of memory available in your machine, particularly if the
image file is to contain debugging information. For this reason, a temporary
disk file is used when all available memory is used by the Watcom Linker.
Normally, the temporary file is created in the default directory. However, by
defining the "tmp" environment variable to be a directory, you can tell the
Watcom Linker where to create the temporary file. This can be particularly
useful if you have a RAM disk. Consider the following definition of the "tmp"
environment variable.
set tmp=\tmp
The Watcom Linker will create the temporary file in the directory "\tmp".
ΓòÉΓòÉΓòÉ 9. QNX: The QNX Executable File Format ΓòÉΓòÉΓòÉ
This chapter deals specifically with aspects of QNX executable files. The QNX
executable file format will only run under the QNX operating system.
Input to the Watcom Linker is specified on the command line and can be
redirected to one or more files or environment strings. The Watcom Linker
command line format is as follows.
wlink {directive}
where directive is any of the following:
ALIAS symbol_name=symbol_name{,symbol_name=symbol_name}
DEBUG dbtype [dblist] |
DISABLE msg_num{,msg_num}
ENDLINK
FILE obj_spec{,obj_spec}
FORMAT QNX [FLAT]
LANGUAGE
LIBFILE obj_file{,obj_file}
LIBPATH path_name{:path_name}
LIBRARY library_file{,library_file}
MODFILE obj_file{,obj_file}
MODTRACE obj_spec{,obj_spec}
NAME exe_file
NEWSEGMENT
OPTION option{,option}
ARTIFICIAL
[NO]CACHE
[NO]CASEEXACT
CVPACK
DOSSEG
ELIMINATE
HEAPSIZE=n
INCREMENTAL
LINEARRELOCS
LONGLIVED
MANGLEDNAMES
MAP[=map_file]
MAXERRORS=n
NAMELEN=n
NODEFAULTLIBS
NORELOCS
OFFSET=n
OSNAME='string'
PACKCODE=n
PACKDATA=n
PRIVILEGE=n
QUIET
REDEFSOK
RESOURCE[=resource_file | 'string']
SHOWDEAD
STACK=n
START=symbol_name
STATICS
SYMFILE[=symbol_file]
[NO]UNDEFSOK
VERBOSE
VFREMOVAL
OPTLIB library_file{,library_file}
PATH path_name{:path_name}
REFERENCE symbol_name{,symbol_name}
SEGMENT seg_desc{,seg_desc}
SORT [GLOBAL] [ALPHABETICAL]
STARTLINK
SYMTRACE symbol_name{,symbol_name}
SYSTEM BEGIN system_name {directive} END
SYSTEM system_name
# comment
@ directive_file
You can view all the directives specific to QNX executable files by simply
typing the following:
wlink ? qnx
Notes:
1. If the file /etc/wlink.hlp exists, the contents of that file will be
displayed when the following command is issued.
wlink ?
2. If all of the directive information does not fit on the command line,
type the following.
wlink
The prompt "WLINK>" will appear on the next line. You can enter as many
lines of directive information as required. Press "Ctrl/Z" followed by
the "Enter" key to terminate the input of directive information if you
are running a DOS, OS/2 or Windows NT-hosted version of the Watcom
Linker. Press "Ctrl/D" to terminate the input of directive information
if you are running a QNX-hosted version of the Watcom Linker.
ΓòÉΓòÉΓòÉ 9.1. QNX: Memory Layout ΓòÉΓòÉΓòÉ
The following describes the segment ordering of an application linked by the
Watcom Linker. Note that this assumes that the "DOSSEG" linker option has been
specified.
1. all segments not belonging to group "DGROUP" with class "CODE"
2. all other segments not belonging to group "DGROUP"
3. all segments belonging to group "DGROUP" with class "BEGDATA"
4. all segments belonging to group "DGROUP" not with class "BEGDATA", "BSS"
or "STACK"
5. all segments belonging to group "DGROUP" with class "BSS"
6. all segments belonging to group "DGROUP" with class "STACK"
A special segment belonging to class "BEGDATA" is defined when linking with
Watcom run-time libraries. This segment is initialized with the hexadecimal
byte pattern "01" and is the first segment in group "DGROUP" so that storing
data at location 0 can be detected.
Segments belonging to class "BSS" contain uninitialized data. Note that this
only includes uninitialized data in segments belonging to group "DGROUP".
Segments belonging to class "STACK" are used to define the size of the stack
used for your application. Segments belonging to the classes "BSS" and
"STACK" are last in the segment ordering so that uninitialized data need not
take space in the executable file.
ΓòÉΓòÉΓòÉ 9.2. QNX: The Watcom Linker Memory Requirements ΓòÉΓòÉΓòÉ
The Watcom Linker uses all available memory when linking an application. For
DOS-hosted versions of the Watcom Linker, this includes expanded memory (EMS)
and extended memory. It is possible for the size of the image being linked to
exceed the amount of memory available in your machine, particularly if the
image file is to contain debugging information. For this reason, a temporary
disk file is used when all available memory is used by the Watcom Linker.
Normally, the temporary file is created in the current working directory.
However, by defining the "TMPDIR" environment variable to be a directory, you
can tell the Watcom Linker where to create the temporary file. This can be
particularly useful if you have a RAM disk. Consider the following definition
of the "TMPDIR" environment variable.
export TMPDIR=/tmp
The Watcom Linker will create the temporary file in the directory "/tmp".
ΓòÉΓòÉΓòÉ 10. Win16: The Win16 Executable and DLL File Formats ΓòÉΓòÉΓòÉ
This chapter deals specifically with aspects of Win16 executable files. The
Win16 executable file format will run under Windows 3.x, Windows 95, and
Windows NT.
Input to the Watcom Linker is specified on the command line and can be
redirected to one or more files or environment strings. The Watcom Linker
command line format is as follows.
WLINK {directive}
where directive is any of the following:
ALIAS alias_name=symbol_name{,alias_name=symbol_name}
ANONYMOUSEXPORT export{,export} | =lbc_file
DEBUG dbtype [dblist] |
DISABLE msg_num{,msg_num}
ENDLINK
EXPORT export{,export}
EXPORT =lbc_file
FILE obj_spec{,obj_spec}
FORMAT WINDOWS [dll_form] [MEMORY] [FONT]
IMPORT import{,import}
LANGUAGE lang
LIBFILE obj_file{,obj_file}
LIBPATH path_name{;path_name}
LIBRARY library_file{,library_file}
MODFILE obj_file{,obj_file}
MODTRACE obj_module{,obj_module}
NAME exe_file
NEWSEGMENT
PATH path_name{;path_name}
OPTION option{,option}
ALIGNMENT=n
ARTIFICIAL
[NO]CACHE
[NO]CASEEXACT
CVPACK
DESCRIPTION 'string'
DOSSEG
ELIMINATE
HEAPSIZE=n
IMPFILE[=imp_file]
IMPLIB[=imp_lib]
INCREMENTAL
MANGLEDNAMES
MANYAUTODATA
MAP[=map_file]
MAXERRORS=n
MODNAME=module_name
NAMELEN=n
NOAUTODATA
NODEFAULTLIBS
OLDLIBRARY=dll_name
ONEAUTODATA
OSNAME='string'
PACKCODE=n
PACKDATA=n
QUIET
REDEFSOK
RESOURCE=resource_file
RWRELOCCHECK
SHOWDEAD
STACK=n
START=symbol_name
STATICS
STUB=stub_name
SYMFILE[=symbol_file]
[NO]UNDEFSOK
VERBOSE
VERSION=major[.minor]
VFREMOVAL
OPTLIB library_file{,library_file}
REFERENCE symbol_name{,symbol_name}
SEGMENT seg_desc{,seg_desc}
SORT [GLOBAL] [ALPHABETICAL]
STARTLINK
SYMTRACE symbol_name{,symbol_name}
SYSTEM BEGIN system_name {directive} END
SYSTEM system_name
# comment
@ directive_file
You can view all the directives specific to Win16 executable files by simply
typing the following:
wlink ? win
Notes:
1. If the file "wlink.hlp" is located in one of the paths specified in the
"PATH" environment variable, the contents of that file will be displayed
when the following command is issued.
wlink ?
2. If all of the directive information does not fit on the command line,
type the following.
wlink
The prompt "WLINK>" will appear on the next line. You can enter as many
lines of directive information as required. Press "Ctrl/Z" followed by
the "Enter" key to terminate the input of directive information if you
are running a DOS, OS/2 or Windows NT-hosted version of the Watcom
Linker. Press "Ctrl/D" to terminate the input of directive information
if you are running a QNX-hosted version of the Watcom Linker.
ΓòÉΓòÉΓòÉ 10.1. Win16: Fixed and Moveable Segments ΓòÉΓòÉΓòÉ
All segments have attributes that tell Windows how to manage the segment. One
of these attributes specifies whether the segment is fixed or moveable.
Moveable segments can be moved in memory to satisfy other memory requests.
When a segment is moved, all near pointers to that segment are still valid
since a near pointer references memory relative to the start of the segment.
However, far pointers are no longer valid once a segment has been moved. Fixed
segments, on the other hand, cannot be moved in memory. A segment must be
fixed if there exists far pointers to that segment that Windows cannot adjust
if that segment were moved.
This is a memory-management issue for real-mode Windows only. However, if a
DLL is marked as "fixed", Windows 3.x will place it in the lower 640K real-mode
memory (regardless of the mode in which Windows 3.x is running). Since the
lower 640K is a limited resource, you normally would want a DLL to be marked as
"moveable".
Most segments, including code and data segments, are moveable. Some exceptions
exist. If your program contains a far pointer, the segment which it references
must be fixed. If it were moveable, the segment address portion of the far
pointer would be invalid when Windows moved the segment.
All non-Windows programs are assigned fixed segments when they run under
Windows. These segments must be fixed since there is no information in the
executable file that describes how segments are referenced. Whenever possible,
your application should consist of moveable segments since fixed segments can
cause memory management problems.
ΓòÉΓòÉΓòÉ 10.2. Win16: Discardable Segments ΓòÉΓòÉΓòÉ
Moveable segments can also be discardable. Memory allocated to a discardable
segment can be freed and used for other memory requests. A "least recently
used" (LRU) algorithm is used to determine which segment to discard when more
memory is required.
Discardable segments are usually segments that do not change once they are
loaded into memory. For example, code segments are discardable since programs
do not usually modify their code segments. When a segment is discarded, it can
be reloaded into memory by accessing the executable file.
Discardable segments must be moveable since they can be reloaded into a
different area in memory than the area they previously occupied. Note that
moveable segments need not be discardable. Obviously, data segments that
contain read/write data cannot be discarded.
ΓòÉΓòÉΓòÉ 10.3. Win16: Dynamic Link Libraries ΓòÉΓòÉΓòÉ
The Watcom Linker can generate two forms of executable files; program modules
and Dynamic Link Libraries. A program module is the executable file that gets
loaded by the operating system when you run your application. A Dynamic Link
Library is really a library of routines that are called by a program module but
not linked into the program module. The executable code in a Dynamic Link
Library is loaded by the operating system during the execution of a program
module when a routine in the Dynamic Link Library is called.
Program modules are contained in files whose name has a file extension of
"exe". Dynamic Link Libraries are contained in files whose name has a file
extension of "dll". The Watcom Linker "FORMAT" directive can be used to select
the type of executable file to be generated.
Let us consider some of the advantages of using Dynamic Link Libraries over
standard libraries.
1. Functions in Dynamic Link Libraries are not linked into your program.
Only references to the functions in Dynamic Link Libraries are placed in
the program module. These references are called import definitions. As
a result, the linking time is reduced and disk space is saved. If many
applications reference the same Dynamic Link Library, the saving in disk
space can be significant.
2. Since program modules only reference Dynamic Link Libraries and do not
contain the actual executable code, a Dynamic Link Library can be updated
without re-linking your application. When your application is executed,
it will use the updated version of the Dynamic Link Library.
3. Dynamic Link Libraries also allow sharing of code and data between the
applications that use them. If many applications that use the same
Dynamic Link Library are executing concurrently, the sharing of code and
data segments improves memory utilization.
ΓòÉΓòÉΓòÉ 10.3.1. Win16: Creating a Dynamic Link Library ΓòÉΓòÉΓòÉ
To create a Dynamic Link Library, you must place the "DLL" keyword following
the system name in the "SYSTEM" directive.
system system windows_dll
In addition, you must specify which functions in the Dynamic Link Library are
to be made available to applications which use it. This is achieved by using
the "EXPORT" directive for each function that can be called by an application.
Dynamic Link Libraries can reference other Dynamic Link Libraries. References
to other Dynamic Link Libraries are resolved by specifying "IMPORT" directives
or using import libraries.
ΓòÉΓòÉΓòÉ 10.3.2. Win16: Using a Dynamic Link Library ΓòÉΓòÉΓòÉ
To use a Dynamic Link Library, you must tell the Watcom Linker which functions
are contained in a Dynamic Link Library and the name of the Dynamic Link
Library. This is achieved in two ways.
The first method is to use the "IMPORT" directive. The "IMPORT" directive
names the function and the Dynamic Link Library it belongs to so that the
Watcom Linker can generate an import definition in the program module.
The second method is to use import libraries. An import library is a standard
library which contains object modules with special object records that define
the functions belonging to a Dynamic Link Library. An import library is
created from a Dynamic Link Library using the Watcom Library Manager. The
resulting import library can then be specified in a "LIBRARY" directive in the
same way one would specify a standard library. See the chapter entitled "The
Watcom Library Manager" in the Watcom C/C++ Tools User's Guide or the Watcom
FORTRAN 77 Tools User's Guide for more information on creating import
libraries.
Using an import library is the preferred method of providing references to
functions in Dynamic Link Libraries. When a Dynamic Link Library is modified,
typically the import library corresponding to the modified Dynamic Link Library
is updated to reflect the changes. Hence, any directive file that specifies
the import library in a "LIBRARY" directive need not be modified. However, if
you are using "IMPORT" directives, you may have to modify the "IMPORT"
directives to reflect the changes in the Dynamic Link Library.
ΓòÉΓòÉΓòÉ 10.4. Win16: Memory Layout ΓòÉΓòÉΓòÉ
The following describes the segment ordering of an application linked by the
Watcom Linker. Note that this assumes that the "DOSSEG" linker option has been
specified.
1. all segments not belonging to group "DGROUP" with class "CODE"
2. all other segments not belonging to group "DGROUP"
3. all segments belonging to group "DGROUP" with class "BEGDATA"
4. all segments belonging to group "DGROUP" not with class "BEGDATA", "BSS"
or "STACK"
5. all segments belonging to group "DGROUP" with class "BSS"
6. all segments belonging to group "DGROUP" with class "STACK"
A special segment belonging to class "BEGDATA" is defined when linking with
Watcom run-time libraries. This segment is initialized with the hexadecimal
byte pattern "01" and is the first segment in group "DGROUP" so that storing
data at location 0 can be detected.
Segments belonging to class "BSS" contain uninitialized data. Note that this
only includes uninitialized data in segments belonging to group "DGROUP".
Segments belonging to class "STACK" are used to define the size of the stack
used for your application. Segments belonging to the classes "BSS" and
"STACK" are last in the segment ordering so that uninitialized data need not
take space in the executable file.
ΓòÉΓòÉΓòÉ 10.5. Win16: The Watcom Linker Memory Requirements ΓòÉΓòÉΓòÉ
The Watcom Linker uses all available memory when linking an application. For
DOS-hosted versions of the Watcom Linker, this includes expanded memory (EMS)
and extended memory. It is possible for the size of the image being linked to
exceed the amount of memory available in your machine, particularly if the
image file is to contain debugging information. For this reason, a temporary
disk file is used when all available memory is used by the Watcom Linker.
Normally, the temporary file is created in the default directory. However, by
defining the "tmp" environment variable to be a directory, you can tell the
Watcom Linker where to create the temporary file. This can be particularly
useful if you have a RAM disk. Consider the following definition of the "tmp"
environment variable.
set tmp=\tmp
The Watcom Linker will create the temporary file in the directory "\tmp".
ΓòÉΓòÉΓòÉ 10.6. Win16: Converting Microsoft Response Files to Directive Files ΓòÉΓòÉΓòÉ
A utility called MS2WLINK can be used to convert Microsoft linker response
files to Watcom Linker directive files. The response files must correspond to
the linker found in version 7 or earlier of Microsoft C. Later versions of
response files such as those used with Microsoft Visual C++ are not entirely
supported.
The same utility can also convert much of the content of IBM OS/2 LINK386
response files since the syntax is similar.
Input to MS2WLINK is processed in the same way as the Microsoft linker
processes its input. The difference is that MS2WLINK writes the corresponding
Watcom Linker directive file to the standard output device instead of a
creating an executable file. The resulting output can be redirected to a disk
file which can then be used as input to the Watcom Linker to produce an
executable file.
Suppose you have a Microsoft linker response file called "test.rsp". You can
convert this file to a Watcom Linker directive file by issuing the following
command.
Example:
ms2wlink @test.rsp >test.lnk
You can now use the Watcom Linker to link your program by issuing the following
command.
Example:
wlink @test
An alternative way to link your application with the Watcom Linker from a
Microsoft response file is to issue the following command.
Example:
ms2wlink @test.rsp | wlink
Since the Watcom Linker gets its input from the standard input device, you do
not have to create a Watcom Linker directive file to link your application.
Note that MS2WLINK can also process module-definition files used for creating
OS/2 applications.
ΓòÉΓòÉΓòÉ 11. Win32: The Win32 Executable and DLL File Formats ΓòÉΓòÉΓòÉ
This chapter deals specifically with aspects of Win32 executable files. The
Win32 executable file format will run under Windows 95, Windows NT, and Phar
Lap's TNT DOS extender. It may also run under Windows 3.x using the Win32S
subsystem (you are restricted to a subset of the Win32 API).
Input to the Watcom Linker is specified on the command line and can be
redirected to one or more files or environment strings. The Watcom Linker
command line format is as follows.
WLINK {directive}
where directive is any of the following:
ALIAS alias_name=symbol_name{,alias_name=symbol_name}
ANONYMOUSEXPORT export{,export} | =lbc_file
COMMIT mem_type
DEBUG dbtype [dblist] |
DISABLE msg_num{,msg_num}
ENDLINK
EXPORT export{,export}
EXPORT =lbc_file
FILE obj_spec{,obj_spec}
FORMAT WINDOWS NT [TNT] [dll_form]
IMPORT import{,import}
LANGUAGE lang
LIBFILE obj_file{,obj_file}
LIBPATH path_name{;path_name}
LIBRARY library_file{,library_file}
MODFILE obj_file{,obj_file}
MODTRACE obj_module{,obj_module}
NAME exe_file
PATH path_name{;path_name}
OPTION option{,option}
ALIGNMENT=n
ARTIFICIAL
[NO]CACHE
[NO]CASEEXACT
CVPACK
DESCRIPTION 'string'
DOSSEG
ELIMINATE
HEAPSIZE=n
IMPFILE[=imp_file]
IMPLIB[=imp_lib]
INCREMENTAL
MANGLEDNAMES
MAP[=map_file]
MAXERRORS=n
MODNAME=module_name
NAMELEN=n
NODEFAULTLIBS
NORELOCS
NOSTDCALL
OBJALIGN=n
OFFSET
OLDLIBRARY=dll_name
OSNAME='string'
QUIET
REDEFSOK
RESOURCE=resource_file
SHOWDEAD
STACK=n
START=symbol_name
STATICS
STUB=stub_name
SYMFILE[=symbol_file]
[NO]UNDEFSOK
VERBOSE
VERSION=major[.minor]
VFREMOVAL
OPTLIB library_file{,library_file}
REFERENCE symbol_name{,symbol_name}
RUNTIME run_option
SEGMENT seg_desc{,seg_desc}
SORT [GLOBAL] [ALPHABETICAL]
STARTLINK
SYMTRACE symbol_name{,symbol_name}
SYSTEM BEGIN system_name {directive} END
SYSTEM system_name
# comment
@ directive_file
You can view all the directives specific to Win32 executable files by simply
typing the following:
wlink ? nt
Notes:
1. If the file "wlink.hlp" is located in one of the paths specified in the
"PATH" environment variable, the contents of that file will be displayed
when the following command is issued.
wlink ?
2. If all of the directive information does not fit on the command line,
type the following.
wlink
The prompt "WLINK>" will appear on the next line. You can enter as many
lines of directive information as required. Press "Ctrl/Z" followed by
the "Enter" key to terminate the input of directive information if you
are running a DOS, OS/2 or Windows NT-hosted version of the Watcom
Linker. Press "Ctrl/D" to terminate the input of directive information
if you are running a QNX-hosted version of the Watcom Linker.
ΓòÉΓòÉΓòÉ 11.1. Win32: Dynamic Link Libraries ΓòÉΓòÉΓòÉ
The Watcom Linker can generate two forms of executable files; program modules
and Dynamic Link Libraries. A program module is the executable file that gets
loaded by the operating system when you run your application. A Dynamic Link
Library is really a library of routines that are called by a program module but
not linked into the program module. The executable code in a Dynamic Link
Library is loaded by the operating system during the execution of a program
module when a routine in the Dynamic Link Library is called.
Program modules are contained in files whose name has a file extension of
"exe". Dynamic Link Libraries are contained in files whose name has a file
extension of "dll". The Watcom Linker "FORMAT" directive can be used to select
the type of executable file to be generated.
Let us consider some of the advantages of using Dynamic Link Libraries over
standard libraries.
1. Functions in Dynamic Link Libraries are not linked into your program.
Only references to the functions in Dynamic Link Libraries are placed in
the program module. These references are called import definitions. As
a result, the linking time is reduced and disk space is saved. If many
applications reference the same Dynamic Link Library, the saving in disk
space can be significant.
2. Since program modules only reference Dynamic Link Libraries and do not
contain the actual executable code, a Dynamic Link Library can be updated
without re-linking your application. When your application is executed,
it will use the updated version of the Dynamic Link Library.
3. Dynamic Link Libraries also allow sharing of code and data between the
applications that use them. If many applications that use the same
Dynamic Link Library are executing concurrently, the sharing of code and
data segments improves memory utilization.
ΓòÉΓòÉΓòÉ 11.1.1. Win32: Creating a Dynamic Link Library ΓòÉΓòÉΓòÉ
To create a Dynamic Link Library, you must place the "DLL" keyword following
the system name in the "SYSTEM" directive.
system system nt_win dll
In addition, you must specify which functions in the Dynamic Link Library are
to be made available to applications which use it. This is achieved by using
the "EXPORT" directive for each function that can be called by an application.
Dynamic Link Libraries can reference other Dynamic Link Libraries. References
to other Dynamic Link Libraries are resolved by specifying "IMPORT" directives
or using import libraries.
ΓòÉΓòÉΓòÉ 11.1.2. Win32: Using a Dynamic Link Library ΓòÉΓòÉΓòÉ
To use a Dynamic Link Library, you must tell the Watcom Linker which functions
are contained in a Dynamic Link Library and the name of the Dynamic Link
Library. This is achieved in two ways.
The first method is to use the "IMPORT" directive. The "IMPORT" directive
names the function and the Dynamic Link Library it belongs to so that the
Watcom Linker can generate an import definition in the program module.
The second method is to use import libraries. An import library is a standard
library which contains object modules with special object records that define
the functions belonging to a Dynamic Link Library. An import library is
created from a Dynamic Link Library using the Watcom Library Manager. The
resulting import library can then be specified in a "LIBRARY" directive in the
same way one would specify a standard library. See the chapter entitled "The
Watcom Library Manager" in the Watcom C/C++ Tools User's Guide or the Watcom
FORTRAN 77 Tools User's Guide for more information on creating import
libraries.
Using an import library is the preferred method of providing references to
functions in Dynamic Link Libraries. When a Dynamic Link Library is modified,
typically the import library corresponding to the modified Dynamic Link Library
is updated to reflect the changes. Hence, any directive file that specifies
the import library in a "LIBRARY" directive need not be modified. However, if
you are using "IMPORT" directives, you may have to modify the "IMPORT"
directives to reflect the changes in the Dynamic Link Library.
ΓòÉΓòÉΓòÉ 11.2. Win32: Memory Layout ΓòÉΓòÉΓòÉ
The following describes the segment ordering of an application linked by the
Watcom Linker. Note that this assumes that the "DOSSEG" linker option has been
specified.
1. all segments not belonging to group "DGROUP" with class "CODE"
2. all other segments not belonging to group "DGROUP"
3. all segments belonging to group "DGROUP" with class "BEGDATA"
4. all segments belonging to group "DGROUP" not with class "BEGDATA", "BSS"
or "STACK"
5. all segments belonging to group "DGROUP" with class "BSS"
6. all segments belonging to group "DGROUP" with class "STACK"
A special segment belonging to class "BEGDATA" is defined when linking with
Watcom run-time libraries. This segment is initialized with the hexadecimal
byte pattern "01" and is the first segment in group "DGROUP" so that storing
data at location 0 can be detected.
Segments belonging to class "BSS" contain uninitialized data. Note that this
only includes uninitialized data in segments belonging to group "DGROUP".
Segments belonging to class "STACK" are used to define the size of the stack
used for your application. Segments belonging to the classes "BSS" and
"STACK" are last in the segment ordering so that uninitialized data need not
take space in the executable file.
ΓòÉΓòÉΓòÉ 11.3. Win32: The Watcom Linker Memory Requirements ΓòÉΓòÉΓòÉ
The Watcom Linker uses all available memory when linking an application. For
DOS-hosted versions of the Watcom Linker, this includes expanded memory (EMS)
and extended memory. It is possible for the size of the image being linked to
exceed the amount of memory available in your machine, particularly if the
image file is to contain debugging information. For this reason, a temporary
disk file is used when all available memory is used by the Watcom Linker.
Normally, the temporary file is created in the default directory. However, by
defining the "tmp" environment variable to be a directory, you can tell the
Watcom Linker where to create the temporary file. This can be particularly
useful if you have a RAM disk. Consider the following definition of the "tmp"
environment variable.
set tmp=\tmp
The Watcom Linker will create the temporary file in the directory "\tmp".
ΓòÉΓòÉΓòÉ 12. Watcom Linker Diagnostic Messages ΓòÉΓòÉΓòÉ
The Watcom Linker issues three classes of messages; fatal errors, errors and
warnings. Each message has a 4-digit number associated with it. Fatal
messages start with the digit 3, error messages start with the digit 2, and
warning messages start with the digit 1. It is possible for a message to be
issued as a warning or an error.
If a fatal error occurs, the linker will terminate immediately and no
executable file will be generated.
If an error occurs, the linker will continue to execute so that all possible
errors are issued. However, no executable file will be generated since these
errors do not permit a proper executable file to be generated.
If a warning occurs, the linker will continue to execute. A warning message is
usually informational and does not prevent the creation of a proper executable
file. However, all warnings should eventually be corrected.
The messages listed contain references to %s, %S, %a, %x, %d, %l, and %f. They
represent strings that are substituted by the Watcom Linker to make the error
message more precise.
1. %s represents a string. This may be a segment or group name, or the name
of a linker directive or option.
2. %S represents the name of a symbol.
3. %a represents an address. The format of the address depends on the
format of the executable file being generated.
4. %x represents a hexadecimal number.
5. %d represents integers in the range -32768 and 32767.
6. %l represents integers in the range -2147483648 and 2147483647.
7. %f represents an executable file format such as DOS, WINDOWS, PHARLAP,
NOVELL, OS2, QNX or ELF.
The following is a list of all warning and error messages produced by the
Watcom Linker followed by a description of the message. A message may contain
more than one reference to "%s". In such a case, the description will
reference them as "%sn" where n is the occurrence of "%s" in the message.
ΓòÉΓòÉΓòÉ 12.1. 2002 ** internal ** - %s ΓòÉΓòÉΓòÉ
If this message occurs, you have found a bug in the linker and should report
it.
ΓòÉΓòÉΓòÉ 12.2. 2008 cannot open %s1 : %s2 ΓòÉΓòÉΓòÉ
An error occurred while trying to open the file "%s1". The reason for the
error is given by "%s2". Generally this error message is issued when the
linker cannot open a file (e.g., an object file or an executable file).
ΓòÉΓòÉΓòÉ 12.3. 3009 dynamic memory exhausted ΓòÉΓòÉΓòÉ
The linker uses all available memory when linking an application. For
DOS-hosted versions of the linker, this includes expanded memory (EMS) and
extended memory. When all available memory is used, a spill file will be used.
Therefore, unless you are low on disk space, the linker will always be able to
generate the executable file. Dynamic memory is the memory the linker uses to
build its internal data structures and symbol table. Dynamic memory is the
amount of unallocated memory available on your machine (including virtual
memory for those operating systems that support it). A spill file is not used
for dynamic memory. If the linker issues this message, it cannot link your
application. The following are suggestions that may help you in this
situation.
1. Concatenate all your object files into one and specify only the resulting
object file as input to the linker. For example, if you are linking in a
DOS environment, you can issue the following DOS command.
C>copy/b *.obj all.obj
This technique only works for OMF-type object files. This significantly
reduces the size of the file list the linker must maintain.
2. Object files may contain a record which specifies the module name. This
information is used by Watcom Debugger to locate modules during a
debugging session and usually contains the full path of the source file.
This can consume a significant amount of memory when many such object
files are being linked. If your source is being compiled by the Watcom C
or C++ compiler, you can use the "nm" option to set the module name to
just the file name. This reduces the amount of memory required by the
linker. If your are using Watcom Debugger to debug your application, you
may have to use the "set source" command so that the source corresponding
to a module can be located.
3. Typically, when you are compiling a program for a large code model, each
module defines a different "text" segment. If you are compiling your
application using the Watcom C or C++ compiler, you can reduce the number
of "text" segments that the linker has to process by specifying the "nt"
option. The "nt" option allows you to specify the name of the "text"
segment so that a group of object files define the same "text" segment.
ΓòÉΓòÉΓòÉ 12.4. 2010,3010 I/O error processing %s1 : %s2 ΓòÉΓòÉΓòÉ
An error has occurred while processing the file "%s1". The cause of the error
is given by "%s2". This error is usually detected while reading from object
and library files or writing to the spill file or executable file. For
example, this error would be issued if a "disk full" condition existed.
ΓòÉΓòÉΓòÉ 12.5. 2011 invalid object file attribute ΓòÉΓòÉΓòÉ
The linker encountered an object file that was not of the format required of an
object file.
ΓòÉΓòÉΓòÉ 12.6. 2012 invalid library file attribute ΓòÉΓòÉΓòÉ
The linker encountered a library file that was not of the format required of a
library file.
ΓòÉΓòÉΓòÉ 12.7. 3013 break key detected ΓòÉΓòÉΓòÉ
The linking process was interrupted by the user from the keyboard.
ΓòÉΓòÉΓòÉ 12.8. 1014 stack segment not found ΓòÉΓòÉΓòÉ
The linker identifies the stack segment by a segment defined as having the
"STACK" attribute. This message is issued if no such segment is encountered.
This usually happens if the linker cannot find the run-time libraries required
to link your application.
ΓòÉΓòÉΓòÉ 12.9. 2015 bad relocation type specified ΓòÉΓòÉΓòÉ
This message is issued if a a relocation is found in an object file which the
linker does not support.
ΓòÉΓòÉΓòÉ 12.10. 2016 %a: absolute target invalid for self-relative relocation ΓòÉΓòÉΓòÉ
This message is issued, for example, if a near call or jump is made to an
external symbol which is defined using the "EQU" assembler directive. "%a"
identifies the location of the near call or jump instruction.
ΓòÉΓòÉΓòÉ 12.11. 2017 bad location specified for self-relative relocation at %a ΓòÉΓòÉΓòÉ
This message is issued if a bad fixup is encountered. "%a" defines the
location of the fixup.
ΓòÉΓòÉΓòÉ 12.12. 2018 relocation offset at %a is out of range ΓòÉΓòÉΓòÉ
This message is issued when the offset part of a relocation exceeds 64K in a
16-bit executable or an Alpha executable. "%a" defines the location of the
fixup. The error is most commonly caused by errors in coding assembly language
routines. Consider a module that references an external symbol that is defined
in a segment different from the one in which the reference occurred. The
module, however, specifies that the segment in which the symbol is defined is
the same segment as the segment that references the symbol. This error is most
commonly caused when the "EXTRN" assembler directive is placed after the
"SEGMENT" assembler directive for the segment referencing the symbol. If the
segment that references the symbol is allocated far enough away from the
segment that defines the symbol, the linker will issue this message.
ΓòÉΓòÉΓòÉ 12.13. 1019 segment relocation at %a ΓòÉΓòÉΓòÉ
This message is issued when a 16-bit segment relocation is encountered and
"FORMAT DOS COM", "FORMAT PHARLAP" or "FORMAT NOVELL" has been specified. None
of the above executable file formats allow segment relocation. "%a" identifies
the location of the segment relocation.
ΓòÉΓòÉΓòÉ 12.14. 2020 size of group %s exceeds 64k by %l bytes ΓòÉΓòÉΓòÉ
The group "%s" has exceeded the maximum size (64K) allowed for a group in a
16-bit executable by "%l" bytes. Usually, the group is "DGROUP" (the default
data segment) and your application has placed too much data in this group. One
of the following may solve this problem.
1. If you are using the Watcom C or C++ compiler, you can place some of your
data in a far segment by using the "far" keyword when defining data. You
can also decrease the value of the data threshold by using the "zt"
compiler option. Any datum whose size exceeds the value of the data
threshold will be placed in a far segment.
2. If you are using the Watcom FORTRAN 77 compiler, you can decrease the
value of the data threshold by using the "dt" compiler option. Any datum
whose size exceeds the value of the data threshold will be placed in a
far segment.
ΓòÉΓòÉΓòÉ 12.15. 2021 size of segment %s exceeds 64k by %l bytes ΓòÉΓòÉΓòÉ
The segment "%s" has exceeded the maximum size (64K) for a segment in a 16-bit
executable. This usually occurs if you are linking a 16-bit application that
has been compiled for a small code model and the size of the application has
grown in such a way that the size of the code segment ("_TEXT") has exceeded
64K. You can compile your application for a large code model if you cannot
reduce the amount of code in your application.
ΓòÉΓòÉΓòÉ 12.16. 2022 cannot have a starting address with an imported symbol ΓòÉΓòÉΓòÉ
When generating an OS/2 executable file, a symbol imported from a DLL cannot be
a start address. When generating a NetWare 386 executable file, a symbol
imported from an NLM cannot be a start address.
ΓòÉΓòÉΓòÉ 12.17. 1023 no starting address found, using %a ΓòÉΓòÉΓòÉ
The starting address defines the location where execution is to begin and must
be defined by a special "module end" record in one of the object files linked
into your application. This message is issued if no such record is encountered
in which case a default starting address, namely "%a", will be used. This
usually happens if the linker cannot find the run-time libraries required to
link your application.
ΓòÉΓòÉΓòÉ 12.18. 2026 redefinition of reserved symbol %s ΓòÉΓòÉΓòÉ
The linker defines certain reserved symbols. These symbols are "_edata",
"_end", "__OVLTAB__", "__OVLSTARTVEC__", "__OVLENDVEC__", "__LOVLLDR__",
"__NOVLLDR__", "__SOVLLDR__", "__LOVLINIT__", "__NOVLINIT__" and
"__SOVLINIT__". The symbols "_edata" and "_end" are defined only if the
"DOSSEG" option is specified. Your application must not attempt to define
these symbols. "%s" identifies the reserved symbol.
ΓòÉΓòÉΓòÉ 12.19. 1027 redefinition of %S ignored ΓòÉΓòÉΓòÉ
The symbol "%S" has been defined by more that one module; the first definition
is used. This is only a warning message. Note that if a symbol is defined
more than once and its address is the same in both cases, no warning will be
issued. This prevents the warning message from being issued when linking
FORTRAN 77 modules that contain common blocks.
ΓòÉΓòÉΓòÉ 12.20. 1028,2028 %S is an undefined reference ΓòÉΓòÉΓòÉ
The symbol "%S" has been referenced but not defined. Check that the spelling
of the symbol is consistent. If you wish the linker to ignore undefined
references, use the "UNDEFSOK" option.
ΓòÉΓòÉΓòÉ 12.21. 2029 premature end of file encountered ΓòÉΓòÉΓòÉ
This error is issued while processing object files and object modules from
libraries and is caused if the end of the file or module is reached before the
"module end" record is encountered. The probable cause is a truncated object
file.
ΓòÉΓòÉΓòÉ 12.22. 2030 multiple starting addresses found ΓòÉΓòÉΓòÉ
The starting address defines the location where execution is to begin and is
defined by a "module end" record in a particular object file. This message is
issued if more than one object file contains a "module end" record that defines
a starting address.
ΓòÉΓòÉΓòÉ 12.23. 2031 segment %s is in group %s and group %s ΓòÉΓòÉΓòÉ
The segment "%s1" has been defined to be in group "%s2" in one module and in
group "%s3" in another module. A segment can only belong to one group.
ΓòÉΓòÉΓòÉ 12.24. 1032 record (type 0x%x) not processed ΓòÉΓòÉΓòÉ
An object record type not supported by the linker has been encountered. This
message is issued when linking object modules created by other compilers or
assemblers that create object files with records that the linker does not
support.
ΓòÉΓòÉΓòÉ 12.25. 2033,3033 directive error near '%s' ΓòÉΓòÉΓòÉ
A syntax error occurred while the linker was processing directives. "%s"
specifies where the error occurred.
ΓòÉΓòÉΓòÉ 12.26. 2034 %a cannot have an offset with an imported symbol ΓòÉΓòÉΓòÉ
An imported symbol is one that was specified in an "IMPORT" directive.
Imported symbols are defined in Windows or OS/2 16-bit DLLs and in Netware 386
NLMs. References to imported symbols must always have an offset value of 0.
If "DosWrite" is an imported symbol, then referencing "DosWrite+2" is illegal.
"%a" defines the location of the illegal reference.
ΓòÉΓòÉΓòÉ 12.27. 1038 DEBUG directive appears after object files ΓòÉΓòÉΓòÉ
This message is issued if the first "DEBUG" directive appears after a "FILE"
directive. A common error is to specify a "DEBUG" directive after the "FILE"
directives in which case no debugging information for those object files is
generated in the executable file.
ΓòÉΓòÉΓòÉ 12.28. 2039 ALIGNMENT value too small ΓòÉΓòÉΓòÉ
The value specified in the "ALIGNMENT" option refers to the alignment of
segments in the executable file. For 16-bit Windows or 16-bit OS/2, segments
in the executable file are pointed to by a segment table. An entry in the
segment table contains a 16-bit value which is a multiple of the alignment
value. Together they form the offset of the segment from the start of the
segment table. The smaller the alignment, the bigger the value required in the
segment table to point to the segment. If this value exceeds 64K, then a
larger alignment value is required to decrease the size that goes in the
segment table.
ΓòÉΓòÉΓòÉ 12.29. 2040 ordinal in IMPORT directive not valid ΓòÉΓòÉΓòÉ
The specified ordinal in the "IMPORT" directive is incorrect (e.g., -1). An
ordinal number must be in the range 0 to 65535.
ΓòÉΓòÉΓòÉ 12.30. 2041 ordinal in EXPORT directive not valid ΓòÉΓòÉΓòÉ
The specified ordinal in the "EXPORT" directive is incorrect (e.g., -1). An
ordinal number must be in the range 0 to 65535.
ΓòÉΓòÉΓòÉ 12.31. 2042 too many IOPL words in EXPORT directive ΓòÉΓòÉΓòÉ
The maximum number of IOPL words for a 16-bit executable is 63.
ΓòÉΓòÉΓòÉ 12.32. 1043 duplicate exported ordinal ΓòÉΓòÉΓòÉ
This message is issued for ordinal numbers specified in an "EXPORT" directive
for symbols belonging to DLLs. This message is issued if an ordinal number is
assigned to two different symbols. A warning is issued and the linker assigns
a non-used ordinal number to the symbol that caused the warning.
ΓòÉΓòÉΓòÉ 12.33. 1044,2044 exported symbol %s not found ΓòÉΓòÉΓòÉ
This message is issued when generating a DLL or NetWare 386 NLM. An attempt
has been made to define an entry point into a DLL or NLM that does not exist.
ΓòÉΓòÉΓòÉ 12.34. 1045 segment attribute defined more than once ΓòÉΓòÉΓòÉ
A segment appearing in a "SEGMENT" directive has been given conflicting or
duplicate attributes.
ΓòÉΓòÉΓòÉ 12.35. 1046 segment name %s not found ΓòÉΓòÉΓòÉ
The segment name specified in a "SEGMENT" directive has not been defined.
ΓòÉΓòÉΓòÉ 12.36. 1047 class name %s not found ΓòÉΓòÉΓòÉ
The class name specified in a "SEGMENT" directive has not been defined.
ΓòÉΓòÉΓòÉ 12.37. 1048 inconsistent attributes for automatic data segment ΓòÉΓòÉΓòÉ
This message is issued for Windows or OS/2 16-bit executable files. Two
conflicting attributes were specified for the automatic data segment. For
example, "LOADONCALL" and "PRELOAD" are conflicting attributes. Only the first
attribute is used.
ΓòÉΓòÉΓòÉ 12.38. 2049 invalid STUB file ΓòÉΓòÉΓòÉ
The stub file is not a valid executable file. The stub file is only used for
OS/2 executable files and Windows (both Win16 and Win32) executable files.
ΓòÉΓòÉΓòÉ 12.39. 1050 invalid DLL specified in OLDLIBRARY option ΓòÉΓòÉΓòÉ
The DLL specified in an "OLDLIBRARY" option is not a valid dynamic link
library.
ΓòÉΓòÉΓòÉ 12.40. 2051 STUB file name same as executable file name ΓòÉΓòÉΓòÉ
When generating an OS/2 or Windows (Win16, Win32) executable file, the stub
file name must not be same as the executable file name.
ΓòÉΓòÉΓòÉ 12.41. 2052 relocation at %a not in the same segment ΓòÉΓòÉΓòÉ
This message is only issued for Windows (Win16), OS/2, Phar Lap, and QNX
executables. A relative fixup must relocate to the same segment. "%a" defines
the location of the fixup.
ΓòÉΓòÉΓòÉ 12.42. 2053 %a: cannot reach a DLL with a relative relocation ΓòÉΓòÉΓòÉ
A reference to a symbol in an OS/2 or Windows 16-bit DLL must not be relative.
"%a" defines the location of the reference.
ΓòÉΓòÉΓòÉ 12.43. 1054 debugging information incompatible: using line numbers only ΓòÉΓòÉΓòÉ
An attempt has been made to link an object file with out-of-date debugging
information.
ΓòÉΓòÉΓòÉ 12.44. 2055 %a: frame must be the same as the target in protected mode ΓòÉΓòÉΓòÉ
Each relocation consists of three components; the location being relocated, the
target (or address being referenced), and the frame (the segment to which the
target is adjusted). In protected mode, the segment of the target must be the
same as the frame. "%a" defines the location of the fixup. This message does
not apply to 32-bit OS/2 and Windows (Win32).
ΓòÉΓòÉΓòÉ 12.45. 2056 cannot find library member %s(%s) ΓòÉΓòÉΓòÉ
Library member "%s2" in library file "%s1" could not be found. This message is
issued if the library file could not be found or the library file did not
contain the specified member.
ΓòÉΓòÉΓòÉ 12.46. 3057 executable format has been established ΓòÉΓòÉΓòÉ
This message is issued if there is more than one "FORMAT" directive.
ΓòÉΓòÉΓòÉ 12.47. 1058 %s option not valid for %s executable ΓòÉΓòÉΓòÉ
The option "%s1" can only be specified if an executable file whose format is
"%s2" is being generated.
ΓòÉΓòÉΓòÉ 12.48. 1059,2059 value for %s too large ΓòÉΓòÉΓòÉ
The value specified for option "%s" exceeds its limit.
ΓòÉΓòÉΓòÉ 12.49. 1060 value for %s incorrect ΓòÉΓòÉΓòÉ
The value specified for option "%s" is not in the allowable range.
ΓòÉΓòÉΓòÉ 12.50. 1061 multiple values specified for REALBREAK ΓòÉΓòÉΓòÉ
The "REALBREAK" option for Phar Lap executables can only be specified once.
ΓòÉΓòÉΓòÉ 12.51. 1062 export and import records not valid for %f ΓòÉΓòÉΓòÉ
This message is issued if a reference to a DLL is encountered and the
executable file format is not one that supports DLLs. The file format is
represented by "%f".
ΓòÉΓòÉΓòÉ 12.52. 2063 invalid relocation for flat memory model at %a ΓòÉΓòÉΓòÉ
A segment relocation in the flat memory model was encountered. "%a" defines
the location of the fixup.
ΓòÉΓòÉΓòÉ 12.53. 2064 cannot combine 32-bit segments with 16-bit segments ΓòÉΓòÉΓòÉ
A 16-bit segment and a 32-bit segment have been encountered. Mixing object
files created by a 286 compiler and object files created by a 386 compiler is
the most probable cause of this error.
ΓòÉΓòÉΓòÉ 12.54. 2065 REALBREAK symbol %s not found ΓòÉΓòÉΓòÉ
The symbol specified in the "REALBREAK" option for Phar Lap executables has not
been defined.
ΓòÉΓòÉΓòÉ 12.55. 2066 invalid relative relocation type for an import at %a ΓòÉΓòÉΓòÉ
This message is issued only if a NetWare 386 executable file is being
generated. An imported symbol is one that was specified in an "IMPORT"
directive or an import library. Any reference to an imported symbol must not
refer to the segment of the imported symbol. "%a" defines the location of the
reference.
ΓòÉΓòÉΓòÉ 12.56. 2067 %a: cannot relocate between code and data in Novell formats ΓòÉΓòÉΓòÉ
This message is issued only if a NetWare 386 executable file is being
generated. Segment relocation is not permitted. "%a" defines the location of
the fixup.
ΓòÉΓòÉΓòÉ 12.57. 2068 absolute segment fixup not valid in protected mode ΓòÉΓòÉΓòÉ
A reference to an absolute location is not allowed in protected mode. A
protected-mode application is one that is being generated for OS/2, FlashTek's
DOS extender, Phar Lap's 386|DOS-Extender, Tenberry Software's DOS/4G or
DOS/4GW DOS extender, Novell's NetWare 386 operating system, Windows NT, or
Windows 95. An absolute location is most commonly defined by the "EQU"
assembler directive.
ΓòÉΓòÉΓòÉ 12.58. 1069 unload CHECK procedure not found ΓòÉΓòÉΓòÉ
This message is issued only if a NetWare 386 executable file is being
generated. The symbol specified in the "CHECK" option has not been defined.
ΓòÉΓòÉΓòÉ 12.59. 2070 START procedure not found ΓòÉΓòÉΓòÉ
This message is issued only if a NetWare 386 executable file is being
generated. The symbol specified in the "START" option has not been defined.
The default "START" symbol is "_Prelude".
ΓòÉΓòÉΓòÉ 12.60. 2071 EXIT procedure not found ΓòÉΓòÉΓòÉ
This message is issued only if a NetWare 386 executable file is being
generated. The symbol specified in the "EXIT" option has not been defined.
The default "STOP" symbol is "_Stop".
ΓòÉΓòÉΓòÉ 12.61. 2073 bad Novell file format specified ΓòÉΓòÉΓòÉ
An invalid NetWare 386 executable file format was specified. Valid formats are
NLM, DSK, NAM and LAN.
ΓòÉΓòÉΓòÉ 12.62. 2074 circular alias found for %s ΓòÉΓòÉΓòÉ
An attempt was made to circularly define the symbol name specified in an ALIAS
directive. For example:
ALIAS foo1=foo2, foo2=foo1
ΓòÉΓòÉΓòÉ 12.63. 1076 %s option multiply specified ΓòÉΓòÉΓòÉ
The option "%s" can only be specified once.
ΓòÉΓòÉΓòÉ 12.64. 1080 file %s is a %d-bit object file ΓòÉΓòÉΓòÉ
A 32-bit attribute was encountered while generating a 16-bit executable file
format, or a 16-bit attribute was encountered while generating a 32-bit
executable file format.
ΓòÉΓòÉΓòÉ 12.65. 2082 invalid record type 0x%x ΓòÉΓòÉΓòÉ
An object record type not recognized by the linker has been encountered. This
message is issued when linking object modules created by other compilers or
assemblers that create object files with records that the linker does not
recognize.
ΓòÉΓòÉΓòÉ 12.66. 2083 cannot reference address %a from frame %x ΓòÉΓòÉΓòÉ
When generating a 16-bit executable, the offset of a referenced symbol was
greater than 64K from the location referencing it.
ΓòÉΓòÉΓòÉ 12.67. 2084 target offset exceeds 64K at %a ΓòÉΓòÉΓòÉ
When generating a 16-bit executable, the computed offset for a symbol exceeds
64K. "%a" defines the location of the fixup.
ΓòÉΓòÉΓòÉ 12.68. 2086 invalid starting address for .COM file ΓòÉΓòÉΓòÉ
The value of the segment of the starting address for a 16-bit DOS "COM" file,
as specified in the map file, must be 0.
ΓòÉΓòÉΓòÉ 12.69. 1087 stack segment ignored in .COM file ΓòÉΓòÉΓòÉ
A stack segment must not be defined when generating a 16-bit DOS "COM" file.
Only a single physical segment is allowed in a DOS "COM" file. The stack is
allocated from the high end of the physical segment. That is, the initial
value of SP is hexadecimal FFFE.
ΓòÉΓòÉΓòÉ 12.70. 3088 virtual memory exhausted ΓòÉΓòÉΓòÉ
This message is similar to the "dynamic memory exhausted" message. The
DOS-hosted version of the linker has run out of memory trying to keep track of
virtual memory blocks. Virtual memory blocks are allocated from expanded
memory, extended memory and the spill file.
ΓòÉΓòÉΓòÉ 12.71. 2089 program too large for a .COM file ΓòÉΓòÉΓòÉ
The total size of a 16-bit DOS "COM" program must not exceed 64K. That is, the
total amount of code and data must be less than 64K since only a single
physical segment is allowed in a DOS "COM" file. You must decrease the size of
your program or generate a DOS "EXE" file.
ΓòÉΓòÉΓòÉ 12.72. 1090 redefinition of %s by %s ignored ΓòÉΓòÉΓòÉ
The symbol "%s1" has been redefined by module "%s2". This message is issued
when the size specified in the "NAMELEN" option has caused two symbols to map
to the same symbol. For example, if the symbols routine1 and routine2 are
encountered and "OPTION NAMELEN=7" is specified, then this message will be
issued since the first seven characters of the two symbols are identical.
ΓòÉΓòÉΓòÉ 12.73. 2092 NEWSEGMENT directive appears before object files ΓòÉΓòÉΓòÉ
The 16-bit "NEWSEGMENT" directive must appear after a "FILE" directive.
ΓòÉΓòÉΓòÉ 12.74. 2093 cannot open %s ΓòÉΓòÉΓòÉ
This message is issued when the linker is unable to open a file and is unable
to determine the cause.
ΓòÉΓòÉΓòÉ 12.75. 2094 i/o error processing %s ΓòÉΓòÉΓòÉ
This message is issued when the linker has encountered an i/o error while
processing the file and is unable to determine the cause. This message may be
issued when reading from object and library files, or writing to the executable
and spill file.
ΓòÉΓòÉΓòÉ 12.76. 1098 Offset option must be a multiple of %dK ΓòÉΓòÉΓòÉ
The value specified with the "OFFSET" option must be a multiple of 4K (4096)
for Phar Lap and QNX executables and a multiple of 64K (65536) for OS/2 and
Windows 32-bit executables.
ΓòÉΓòÉΓòÉ 12.77. 2099 symbol name too long: %s ΓòÉΓòÉΓòÉ
The maximum size (approximately 2048) of a symbol has been exceeded. Reduce
the size of the symbol to avoid this error.
ΓòÉΓòÉΓòÉ 12.78. 1101 invalid incremental information file ΓòÉΓòÉΓòÉ
The incremental information file is corrupt or from an older version of the
compiler. The old information file and the executable will be deleted and new
ones will be generated.
ΓòÉΓòÉΓòÉ 12.79. 1102 object file %s not found for tracing ΓòÉΓòÉΓòÉ
A "SYMTRACE" or "MODTRACE" directive contained an object file (namely %s) that
could not be found.
ΓòÉΓòÉΓòÉ 12.80. 1103 library module %s(%s) not found for tracing ΓòÉΓòÉΓòÉ
A "SYMTRACE" or "MODTRACE" directive contained an object module (namely module
%s1 in library %s2 ) that could not be found.
ΓòÉΓòÉΓòÉ 12.81. 1107 undefined system name: %s ΓòÉΓòÉΓòÉ
The name %s was referenced in a "SYSTEM" directive but never defined by a
system block definition.
ΓòÉΓòÉΓòÉ 12.82. 1108 system %s defined more than once ΓòÉΓòÉΓòÉ
The name %s has appeared in a system definition block more than once.
ΓòÉΓòÉΓòÉ 12.83. 1109 OFFSET option is less than the stack size ΓòÉΓòÉΓòÉ
For the QNX operating system, the stack is placed at the front of the
executable image and thus the initial load address must leave enough room for
the stack.
ΓòÉΓòÉΓòÉ 12.84. 1110 library members not allowed in libfile ΓòÉΓòÉΓòÉ
Only object files are allowed in a "LIBFILE" directive. This message will be
issued if a module from a library file is specified in a "LIBFILE" directive.
ΓòÉΓòÉΓòÉ 12.85. 1111 error in default system block ΓòÉΓòÉΓòÉ
The default system block definition (system name "286" for 16-bit applications)
and (system name "386" for 32-bit applications) contains a directive error.
The system name "286" or "386" is automatically referenced by the linker when
the format of the executable cannot be determined (i.e. no "FORMAT" directive
has been specified).
ΓòÉΓòÉΓòÉ 12.86. 3114 environment name specified incorrectly ΓòÉΓòÉΓòÉ
This message is specified if the environment variable is not properly enclosed
between two percent (%) characters.
ΓòÉΓòÉΓòÉ 12.87. 1115 environment name %s not found ΓòÉΓòÉΓòÉ
The environment variable %s has not been defined in the environment space.
ΓòÉΓòÉΓòÉ 12.88. 1117 segment number too high for a movable entry point ΓòÉΓòÉΓòÉ
The segment number of a moveable segment must not exceed 255 for 16-bit
executables. Reduce the number of segments or use the "PACKCODE" option.
ΓòÉΓòÉΓòÉ 12.89. 1118 heap size too large ΓòÉΓòÉΓòÉ
This message is issued if the size of the heap, stack and the default data
segment (group DGROUP) exceeds 64K for 16-bit executables.
ΓòÉΓòÉΓòÉ 12.90. 2119 wlib import statement incorrect ΓòÉΓòÉΓòÉ
The "EXPORT" directive allows you to specify a library command file. This
command file is scanned for any librarian commands that create import library
entries. An invalid command was detected. See the section entitled "The
EXPORT Directive" for the correct format of these commands.
ΓòÉΓòÉΓòÉ 12.91. 2120 application too large to run under DOS ΓòÉΓòÉΓòÉ
This message is issued if the size of the 16-bit DOS application exceeds 1M.
ΓòÉΓòÉΓòÉ 12.92. 1121 '%s' has already been exported ΓòÉΓòÉΓòÉ
The linker has detected an attempt to export a symbol more than once. For
example, a name appearing in more than one "EXPORT" directive will cause this
message to be issued. Also, if you have declared a symbol as an export in your
source and have also specified the same symbol in an "EXPORT" directive, this
message will be issued. This message is only a warning.
ΓòÉΓòÉΓòÉ 12.93. 3122 no FILE directives found ΓòÉΓòÉΓòÉ
This message is issued if no "FILE" directive has been specified. In other
words, you have specified no object files to link.
ΓòÉΓòÉΓòÉ 12.94. 3123 overlays are not supported in this version of the linker ΓòÉΓòÉΓòÉ
This version of the linker does not support the creation of overlaid 16-bit
executables.
ΓòÉΓòÉΓòÉ 12.95. 1124 lazy reference for %S has different default resolutions ΓòÉΓòÉΓòÉ
A lazy external reference is one which has two resolutions: a preferred one
and a default one which is used if the preferred one is not found. In this
case, the linker has found two lazy references that have the same preferred
resolution but different default resolutions.
ΓòÉΓòÉΓòÉ 12.96. 1125 multiple aliases found for %S ΓòÉΓòÉΓòÉ
The linker has found a name which has been aliased to two different symbols.
ΓòÉΓòÉΓòÉ 12.97. 1126 %s has been modified: doing full relink ΓòÉΓòÉΓòÉ
The linker has determined that the time stamps on the executable file and
symbolic information file (.sym) are different. An incremental link will not
be done.
ΓòÉΓòÉΓòÉ 12.98. 2127 cannot export symbol %S ΓòÉΓòÉΓòÉ
An attempt was made to export a symbol defined with an absolute address or to
export an imported symbol. It is not possible to export these symbols with the
"EXPORT" directive.
ΓòÉΓòÉΓòÉ 12.99. 3128 directive error near beginning of input ΓòÉΓòÉΓòÉ
The linker detected an error at the start of the command line.
ΓòÉΓòÉΓòÉ 12.100. 3129 address information too large ΓòÉΓòÉΓòÉ
The linker has encountered a segment that appears in more than 11000 object
files. An empty segment does not affect this limit. This can only occur with
WATCOM debugging information. If this message appears, switch to DWARF
debugging information.
ΓòÉΓòÉΓòÉ 12.101. 1130 %s is an invalid shared nlm file ΓòÉΓòÉΓòÉ
The NLM specified in a "SHAREDNLM" option is not valid.
ΓòÉΓòÉΓòÉ 12.102. 3131 cannot open spill file: file already exists ΓòÉΓòÉΓòÉ
All 26 of the DOS-hosted linker's possible spill file names are in use. Spill
files can accumulate when linking on a multi-tasking system and the directory
in which the spill file is created is identical for each invocation of the
linker.
ΓòÉΓòÉΓòÉ 12.103. 2132 curly brace delimited list incorrect ΓòÉΓòÉΓòÉ
A list delimited by curly braces is not correct. The most likely cause is a
missing right brace.
ΓòÉΓòÉΓòÉ 12.104. 1133 no realbreak specified for 16-bit code ΓòÉΓòÉΓòÉ
While generating a Phar Lap executable file, both 16-bit and 32-bit code was
linked together and no "REALBREAK" option has been specified. A warning
message is issued since this may be a potential problem.
ΓòÉΓòÉΓòÉ 12.105. 1134 %s is an invalid message file ΓòÉΓòÉΓòÉ
The file specified in a "MESSAGE" option for NetWare 386 executable files is
invalid.
ΓòÉΓòÉΓòÉ 12.106. 1136 relocation to a read/write data segment found at %a ΓòÉΓòÉΓòÉ
The "RWRELOCCHECK" option for 16-bit Windows (Win16) executables has been
specified and the linker has detected a segment relocation to a read/write data
segment.
ΓòÉΓòÉΓòÉ 12.107. 3137 too many errors encountered ΓòÉΓòÉΓòÉ
This message is issued when the number of error messages issued by the linker
exceeds the number specified by the "MAXERRORS" option.
ΓòÉΓòÉΓòÉ 12.108. 3138 invalid filename '%s' ΓòÉΓòÉΓòÉ
The linker performs a simple filename validation whenever a filename is
specified to the linker. For example, a directory specification is not a valid
filename.
ΓòÉΓòÉΓòÉ 12.109. 3139 cannot have both 16-bit and 32-bit object files ΓòÉΓòÉΓòÉ
It is impossible to mix 16-bit code and 32-bit code in the same executable when
generating a QNX executable file.
ΓòÉΓòÉΓòÉ 12.110. 1140 invalid message number ΓòÉΓòÉΓòÉ
An invalid message number has been specified in a "DISABLE" directive.
ΓòÉΓòÉΓòÉ 12.111. 1141 virtual function table record for %s mismatched ΓòÉΓòÉΓòÉ
The linker performs a consistency check to ensure that the C++ compiler has not
generated incorrect virtual function information. If the message is issued,
please report this problem.
ΓòÉΓòÉΓòÉ 12.112. 1143 not enough memory to sort map file symbols ΓòÉΓòÉΓòÉ
There was not enough memory for the linker to sort the symbols in the "Memory
Map" portion of the map file. This will only occur when the "SORT GLOBAL"
option has been specified.
ΓòÉΓòÉΓòÉ 12.113. 1145 %S is both pure virtual and non-pure virtual ΓòÉΓòÉΓòÉ
A function has been declared both as "pure" and "non-pure" virtual.
ΓòÉΓòÉΓòÉ 12.114. 2146 %s is an invalid object file ΓòÉΓòÉΓòÉ
Something was encountered in the object file that cannot be processed by the
linker.
ΓòÉΓòÉΓòÉ 12.115. 3147 Ambiguous format specified ΓòÉΓòÉΓòÉ
Not enough of the FORMAT directive attributes were specified to enable the
linker to determine the executable file format. For example,
FORMAT OS2
will generate this message.
ΓòÉΓòÉΓòÉ 12.116. 1148 Invalid segment type specified ΓòÉΓòÉΓòÉ
The segment type must be one of CODE or DATA.
ΓòÉΓòÉΓòÉ 12.117. 1149 Only one debugging format can be specified ΓòÉΓòÉΓòÉ
The debugging format must be one of WATCOM, Codeview, Dwarf (default), or
Novell. You cannot specify multiple debugging formats.
ΓòÉΓòÉΓòÉ 12.118. 1150 file %s has code for a different processor ΓòÉΓòÉΓòÉ
An object file has been encountered which contains code compiled for a
different processor (e.g., an Intel application and an Alpha object file).
ΓòÉΓòÉΓòÉ 12.119. 2151 big endian code not supported ΓòÉΓòÉΓòÉ
Big endian code is not supported by the linker.
ΓòÉΓòÉΓòÉ 12.120. 2152 no dictionary found ΓòÉΓòÉΓòÉ
No symbol search dictionary was found in a library that the linker attempted to
process.
ΓòÉΓòÉΓòÉ 12.121. 2154 cannot execute %s1 : %s2 ΓòÉΓòÉΓòÉ
An attempt by the linker to spawn another application failed. The application
is specified by "%s1" and the reason for the failure is specified by "%s2".
ΓòÉΓòÉΓòÉ 12.122. 2155 relocation at %a to an improperly aligned target ΓòÉΓòÉΓòÉ
Some relocations in Alpha executables require that the object be aligned on a 4
byte boundary.
ΓòÉΓòÉΓòÉ 12.123. 2156 OPTION INCREMENTAL must be one of the first directives specified ΓòÉΓòÉΓòÉ
The option must be specified before any option or directive which modifies the
linker's symbol table (e.g., IMPORT, EXPORT, REFERENCE, ALIAS).
ΓòÉΓòÉΓòÉ 12.124. 3157 no code or data present ΓòÉΓòÉΓòÉ
The linker requires that there be at least 1 byte of either code or data in the
executable.
ΓòÉΓòÉΓòÉ 12.125. 1158 problem adding resource information ΓòÉΓòÉΓòÉ
The resource file is invalid or corrupt.
ΓòÉΓòÉΓòÉ 12.126. 3159 incremental linking only supports DWARF debugging information ΓòÉΓòÉΓòÉ
When OPTION INCREMENTAL is used, you cannot specify non-Dwarf debugging
information for the executable. You must specify DEBUG DWARF when requesting
debugging information.
ΓòÉΓòÉΓòÉ 12.127. 3160 incremental linking does not support dead code elimination ΓòÉΓòÉΓòÉ
When OPTION INCREMENTAL is used, you cannot specify OPTION ELIMINATE.
ΓòÉΓòÉΓòÉ 12.128. 1162 relocations on iterated data not supported ΓòÉΓòÉΓòÉ
An object file was encountered that contained an iterated data record that
requires relocation. This is most commonly caused by a module coded in
assembly language.
ΓòÉΓòÉΓòÉ 12.129. 1163 module has not been compiled with the "zv" option ΓòÉΓòÉΓòÉ
When OPTION VFREMOVAL is used, all object files must be compiled with the "zv"
option. The linker has detected an object file that has not been compiled with
this option.
ΓòÉΓòÉΓòÉ 12.130. 3164 incremental linking does not support virtual function removal ΓòÉΓòÉΓòÉ
When OPTION INCREMENTAL is used, you cannot also specify OPTION VFREMOVAL.
ΓòÉΓòÉΓòÉ 12.131. 1165 resource file %s too big ΓòÉΓòÉΓòÉ
The resource file specified in OPTION RESOURCE was too big to fit inside the
QNX executable. The maximum size is approximately 32000 bytes.
ΓòÉΓòÉΓòÉ 12.132. 2166 both %s1 and %s2 marked as starting symbols ΓòÉΓòÉΓòÉ
If the linker sees that there is more than one starting address specified in
the program and they have symbol names associated with them, it will emit this
error message. If there is more than one starting address specified and at
least one of them is unnamed, it will issue message 2030.