OS/2 Shareware BBS: 10 Tools/10-Tools.zip/watc11up.zip/core_hlp_os2.zip/binp/help/lguide.inf

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.