Index of Topics

- # -

The # Directive

- 1 -

1014 stack segment not found
1019 segment relocation at %a
1023 no starting address found, using %a
1027 redefinition of %S ignored
1028,2028 %S is an undefined reference
1032 record (type 0x%x) not processed
1038 DEBUG directive appears after object files
1043 duplicate exported ordinal
1044,2044 exported symbol %s not found
1045 segment attribute defined more than once
1046 segment name %s not found
1047 class name %s not found
1048 inconsistent attributes for automatic data segment
1050 invalid DLL specified in OLDLIBRARY option
1054 debugging information incompatible:  using line numbers only
1058 %s option not valid for %s executable
1059,2059 value for %s too large
1060 value for %s incorrect
1061 multiple values specified for REALBREAK
1062 export and import records not valid for %f
1069 unload CHECK procedure not found
1072 SECTION directive not allowed in root
1076 %s option multiply specified
1080 file %s is a %d-bit object file
1087 stack segment ignored in .COM file
1090 redefinition of %s by %s ignored
1098 Offset option must be a multiple of %dK
1101 invalid incremental information file
1102 object file %s not found for tracing
1103 library module %s(%s) not found for tracing
1105 cannot reserve %l bytes of extra overlay space
1107 undefined system name:  %s
1108 system %s defined more than once
1109 OFFSET option is less than the stack size
1110 library members not allowed in libfile
1111 error in default system block
1115 environment name %s not found
1116 overlay area must be at least %l bytes
1117 segment number too high for a movable entry point
1118 heap size too large
1121 '%s' has already been exported
1124 lazy reference for %S has different default resolutions
1125 multiple aliases found for %S
1126 %s has been modified:  doing full relink
1130 %s is an invalid shared nlm file
1133 no realbreak specified for 16-bit code
1134 %s is an invalid message file
1136 segment relocation to a read/write data segment found at %a(%S)
1140 invalid message number
1141 virtual function table record for %s mismatched
1143 not enough memory to sort map file symbols
1145 %S is both pure virtual and non-pure virtual
1148 Invalid segment type specified
1149 Only one debugging format can be specified
1150 file %s has code for a different processor
1158 problem adding resource information
1162 relocations on iterated data not supported
1163 module has not been compiled with the "zv" option
1165 resource file %s too big
1167 NLM internal name (%s) truncated
1170 directive %s can only occur once
1171 locally defined symbol %s imported
1172 stack size is less than %d bytes.
1174 IOPL bytes in EXPORT directive odd, ignoring low bit
1175 symbol %s not found for tracing

- 2 -

2002 ** internal ** - %s
2008 cannot open %s1 :  %s2
2010,3010 I/O error processing %s1 :  %s2
2011 invalid object file attribute
2012 invalid library file attribute
2015 bad relocation type specified
2016 %a:  absolute target invalid for self-relative relocation
2017 bad location specified for self-relative relocation at %a
2018 relocation offset at %a is out of range
2020 size of group %s exceeds 64k by %l bytes
2021 size of segment %s exceeds 64k by %l bytes
2022 cannot have a starting address with an imported symbol
2024 missing overlay loader
2025 short vector %d is out of range
2026 redefinition of reserved symbol %s
2029 premature end of file encountered
2030 multiple starting addresses found
2031 segment %s is in group %s and group %s
2033,3033 directive error near '%s'
2034 %a cannot have an offset with an imported symbol
2039 ALIGNMENT value too small
2040 ordinal in IMPORT directive not valid
2041 ordinal in EXPORT directive not valid
2042 too many IOPL words in EXPORT directive
2049 invalid STUB file
2051 STUB file name same as executable file name
2052 relocation at %a not in the same segment
2053 %a:  cannot reach a DLL with a relative relocation
2055 %a:  frame must be the same as the target in protected mode
2056 cannot find library member %s(%s)
2063 invalid relocation for flat memory model at %a
2064 cannot combine 32-bit segments (%s1) with 16-bit segments (%s2)
2065 REALBREAK symbol %s not found
2066 invalid relative relocation type for an import at %a
2067 %a:  cannot relocate between code and data in Novell formats
2068 absolute segment fixup not valid in protected mode
2070 START procedure not found
2071 EXIT procedure not found
2073 bad Novell file format specified
2074 circular alias found for %s
2075 expecting an END directive
2082 invalid record type 0x%x
2083 cannot reference address %a from frame %x
2084 target offset exceeds 64K at %a
2086 invalid starting address for .COM file
2089 program too large for a .COM file
2091 group %s is in more than one overlay
2092 NEWSEGMENT directive appears before object files
2093 cannot open %s
2094 i/o error processing %s
2099 symbol name too long:  %s
2119 wlib import statement incorrect
2120 application too large to run under DOS
2127 cannot export symbol %S
2132 curly brace delimited list incorrect
2146 %s is an invalid object file
2151 big endian code not supported
2152 no dictionary found
2154 cannot execute %s1 :  %s2
2155 relocation at %a to an improperly aligned target
2156 OPTION INCREMENTAL must be one of the first directives specified
2166 both %s1 and %s2 marked as starting symbols
2169 location counter already beyond fixed segment address %a

- 3 -

3009 dynamic memory exhausted
3013 break key detected
3057 executable format has been established
3088 virtual memory exhausted
3097 too many library modules
3114 environment name specified incorrectly
3122 no FILE directives found
3123 overlays are not supported in this version of the linker
3128 directive error near beginning of input
3129 address information too large
3131 cannot open spill file:  file already exists
3135 need exactly 1 overlay area with dynamic overlay manager
3137 too many errors encountered
3138 invalid filename '%s'
3139 cannot have both 16-bit and 32-bit object files
3147 Ambiguous format specified
3157 no code or data present
3159 incremental linking only supports DWARF debugging information
3160 incremental linking does not support dead code elimination
3164 incremental linking does not support virtual function removal
3168 exactly one export must exist for VxD format
3173 default data segment exceeds maximum size by %l bytes

- @ -

The @ Directive

- A -

The ALIAS Directive
The ALIGNMENT Option
All Debugging Information - DEBUG WATCOM ALL
The ANONYMOUSEXPORT Directive
The AREA Option
The ARTIFICIAL Option
The AUTOSECTION Directive
The AUTOUNLOAD Option

- B -

The BEGIN Directive

- C -

The CACHE Option
The CASEEXACT Option
The CHECK Option
The CHECKSUM Option
The COMMIT Directive
Converting Libraries Created using Phar Lap 386|LIB
The COPYRIGHT Option
The CUSTOM Option
The CVPACK Option

- D -

The DEBUG Directive
The DESCRIPTION Option
The DISABLE Directive
The DISTRIBUTE Option
DOS:  Converting Microsoft Response Files to Directive Files
DOS:  Defining Overlay Structures
DOS:  How Overlay Files are Opened
DOS:  Increasing the Dynamic Overlay Area
DOS:  Memory Layout
DOS:  Nested Overlay Structures
DOS:  Rules About Overlays
DOS:  The DOS Executable File Format
DOS:  The Dynamic Overlay Manager
DOS:  The Open Watcom Linker Memory Requirements
DOS:  Using Overlays
The DOSSEG Option
The DYNAMIC Option

- E -

ELF:  Memory Layout
ELF:  The ELF Executable File Format
The ELIMINATE Option
The END Directive
The ENDLINK Directive
The EXIT Option
EXPORT - ELF only
EXPORT - Netware only
EXPORT - OS/2, Win16, Win32 only
The EXPORT Directive

- F -

The FARCALLS Option
The FILE Directive
The FILLCHAR Option
The FIXEDLIB Directive
The FORCEVECTOR Directive
The FORMAT Directive
The FULLHEADER Option

- G -

Global Symbol Information
Global Symbols for the NetWare Debugger - DEBUG NOVELL

- H -

The HEAPSIZE Option
The HELP Option
The HSHIFT Option

- I -

The IMPFILE Option
The IMPLIB Option
IMPORT - ELF only
IMPORT - Netware only
IMPORT - OS/2, Win16, Win32 only
The IMPORT Directive
The INCREMENTAL Option
The INTERNALRELOCS Option

- L -

The LANGUAGE Directive
The LARGEADDRESSAWARE Option
The LIBFILE Directive
The LIBPATH Directive
The LIBRARY Directive
Line Numbering Information - DEBUG WATCOM LINES
The LINEARRELOCS Option
Linker Directives and Options
Linking 16-bit x86 DOS .COM Executable Files
Linking 16-bit x86 DOS Executable Files
Linking 16-bit x86 Executable Files
Linking 16-bit x86 OS/2 Dynamic Link Libraries
Linking 16-bit x86 OS/2 Executable Files
Linking 16-bit x86 QNX Executable Files
Linking 16-bit x86 Windows 3.x Dynamic Link Libraries
Linking 16-bit x86 Windows 3.x Executable Files
Linking 32-bit x86 CauseWay Dynamic Link Libraries
Linking 32-bit x86 CauseWay Executable Files
Linking 32-bit x86 DOS/4GW Executable Files
Linking 32-bit x86 Executable Files
Linking 32-bit x86 Extended Windows 3.x Dynamic Link Libraries
Linking 32-bit x86 Extended Windows 3.x Executable
Linking 32-bit x86 FlashTek Executable Files
Linking 32-bit x86 Novell NetWare Loadable Modules
Linking 32-bit x86 OS/2 Dynamic Link Libraries
Linking 32-bit x86 OS/2 Executable Files
Linking 32-bit x86 OS/2 Presentation Manager Executable Files
Linking 32-bit x86 Phar Lap Executable Files
Linking 32-bit x86 Phar Lap TNT Executable Files
Linking 32-bit x86 PMODE/W Executable Files
Linking 32-bit x86 QNX Executable Files
Linking 32-bit x86 RDOS Dynamic Link Libraries
Linking 32-bit x86 RDOS Executable Files
Linking 32-bit x86 Windows 3.x or 9x Virtual Device Driver
Linking 32-bit x86 Windows 95 Dynamic Link Libraries
Linking 32-bit x86 Windows 95 Executable Files
Linking 32-bit x86 Windows NT Character-Mode Executable Files
Linking 32-bit x86 Windows NT Dynamic Link Libraries
Linking 32-bit x86 Windows NT Windowed Executable Files
Linking Executable Files for Various Systems
The LINKVERSION Option
Local Symbol Information - DEBUG WATCOM LOCALS
The LONGLIVED Option

- M -

The MANGLEDNAMES Option
The MANYAUTODATA Option
The MAP Option
The MAXDATA Option
The MAXERRORS Option
The MESSAGES Option
The MINDATA Option
The MIXED1632 Option
The MODFILE Directive
The MODNAME Option
The MODTRACE Directive
The MODULE Directive
The MULTILOAD Option

- N -

The NAME Directive
The NAMELEN Option
NetWare:  Memory Layout
NetWare:  NetWare Loadable Modules
NetWare:  The NetWare O/S Executable File Format
The NEWFILES Option
The NEWSEGMENT Directive
The NLMFLAGS Option
The NOAUTODATA Option
The NODEFAULTLIBS Option
The NOEXTENSION Option
The NOINDIRECT Option
The NORELOCS Option
The NOSTDCALL Option
The NOSTUB Option
The NOVECTOR Directive

- O -

The OBJALIGN Option
OFFSET - OS/2, Win32, ELF only
OFFSET - PharLap only
OFFSET - QNX only
OFFSET - RAW only
The OFFSET Option
The OLDLIBRARY Option
The ONEAUTODATA Option
The ONLYEXPORTS Debugging Option
The Open Watcom Linker
Open Watcom Linker Diagnostic Messages
The OPTION Directive
The OPTLIB Directive
The ORDER Directive
OS/2:  Converting Microsoft Response Files to Directive Files
OS/2:  Creating a Dynamic Link Library
OS/2:  Dynamic Link Libraries
OS/2:  Memory Layout
OS/2:  The OS/2 Executable and DLL File Formats
OS/2:  Using a Dynamic Link Library
The OSDOMAIN Option
The OSNAME Option
The OSVERSION Option
The OUTPUT Directive
The OVERLAY Directive

- P -

The PACKCODE Option
The PACKDATA Option
The PATH Directive
Phar Lap:  32-bit Protected-Mode Applications
Phar Lap:  Memory Layout
Phar Lap:  Memory Usage
Phar Lap:  The Open Watcom Linker Memory Requirements
Phar Lap:  The Phar Lap Executable File Format
The PRIVILEGE Option
The PROTMODE Option
The PSEUDOPREEMPTION Option

- Q -

QNX:  Memory Layout
QNX:  The QNX Executable File Format
The QUIET Option

- R -

RAW:  Converting Microsoft Response Files to Directive Files
RAW:  Memory Layout
RAW:  The Open Watcom Linker Memory Requirements
RAW:  The RAW File Format
The REDEFSOK Option
The REENTRANT Option
The REFERENCE Directive
Removing Debugging Information from an Executable File
RESOURCE - OS/2, Win16, Win32 only
RESOURCE - QNX only
The RESOURCE Directive
The RESOURCE Option
RUNTIME - ELF only
RUNTIME - PharLap only
RUNTIME - Win32 only
The RUNTIME Directive
The RWRELOCCHECK Option

- S -

The SCREENNAME Option
Searching for Libraries Specified in Environment Variables
Searching for Optional Libraries Specified in Environment Variables
The SECTION Directive
The SEGMENT Directive
The SHARELIB Option
The SHOWDEAD Option
The SMALL Option
The SORT Directive
Special System Names
The STACK Option
The STANDARD Option
The START Option
The STARTLINK Directive
The STATICS Option
The STUB Option
The SYMFILE Option
The SYMTRACE Directive
The SYNCHRONIZE Option
The SYSTEM Directive

- T -

The THREADNAME Option
The TOGGLERELOCS Option
Typing Information - DEBUG WATCOM TYPES

- U -

The UNDEFSOK Option
Using DEBUG Directives
Using the SYSTEM Directive

- V -

The VECTOR Directive
The VERBOSE Option
The VERSION Option
The VFREMOVAL Option

- W -

Win16:  Converting Microsoft Response Files to Directive Files
Win16:  Creating a Dynamic Link Library
Win16:  Discardable Segments
Win16:  Dynamic Link Libraries
Win16:  Fixed and Moveable Segments
Win16:  Memory Layout
Win16:  The Win16 Executable and DLL File Formats
Win16:  Using a Dynamic Link Library
Win32:  Creating a Dynamic Link Library
Win32:  Dynamic Link Libraries
Win32:  Memory Layout
Win32:  The Win32 Executable and DLL File Formats
Win32:  Using a Dynamic Link Library
WinVxD:  Memory Layout
WinVxD:  The Windows Virtual Device Driver File Format

- X -

The XDCDATA Option

- Z -

ZDOS:  Converting Microsoft Response Files to Directive Files
ZDOS:  Memory Layout
ZDOS:  The Open Watcom Linker Memory Requirements
ZDOS:  The ZDOS Executable File Format

The Open 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 object library format (Microsoft, GNU or BSD compatible).

• DOS executable files
• RDOS executable files including Dynamic Link Libraries
• ZDOS executable files
• ELF executable files
• executable files that run under CauseWay DOS extender including Dynamic Link Libraries
• executable files that run under Tenberry Software's DOS/4G and DOS/4GW DOS extenders, and compatible products
• executable files that run under FlashTek's DOS extender
• executable files that run under Phar Lap's 386|DOS-Extender
• NetWare Loadable Modules (NLMs) that run under Novell's NetWare 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
• raw binary images
• Intel Hex files (Hex80, Hex86 and extended linear)

• DOS
• ZDOS
• Linux
• OS/2
• QNX
• Windows NT/2000/XP
• Windows 95/98/Me

Linking Executable Files for Various Systems

Using the SYSTEM Directive

System

Description

causeway

32-bit x86 CauseWay executable

cwdllr

32-bit x86 CauseWay Dynamic Link Library (register calling convention)

cwdlls

32-bit x86 CauseWay Dynamic Link Library (stack calling convention)

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.  Uses original Novell developer kit (NOVH + NOVI).  This is a legacy system type.  It is recommended to use one of the netware_clib or netware_libc system types instead.

novell

synonym for "netware".  This is a legacy system type.  It is recommended to use one of the netware_clib or netware_libc system types instead.

netware_libc

32-bit x86 NetWare Loadable Module.  Targetted for Novells LibC based environment on NetWare 5 and later.  Uses the full Open Watcom run-time library for NetWare.

netware_libc_lite

32-bit x86 NetWare Loadable Module.  Targetted for Novells LibC based environment on NetWare 5 and later.  Uses the thin Open Watcom run-time library support for NetWare and consumes C library functionality from the server libraries.

netware_clib

32-bit x86 NetWare Loadable Module.  Targetted for Novells traditional CLIB based environment on NetWare 3 and later.   Uses the full Open Watcom run-time library for NetWare.

netware_clib_lite

32-bit x86 NetWare Loadable Module.  Targetted for Novells traditional CLIB based environment on NetWare 3 and later.   Uses the thin Open Watcom run-time library support for NetWare and consumes C library functionality from the server libraries.

os2

16-bit x86 OS/2 executable

os2_dll

16-bit x86 OS/2 Dynamic Link Library

os2_pm

16-bit x86 OS/2 Presentation Manager executable

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

pmodew

32-bit x86 PMODE/W executable

tnt

32-bit x86 Phar Lap TNT executable

rdos

32-bit x86 RDOS executable

rdos_dll

32-bit x86 RDOS Dynamic Link Library

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

win_vxd

32-bit x86 Windows 3.x or 9x Virtual Device Driver

win95

32-bit x86 Windows 9x executable

win95 dll

32-bit x86 Windows 9x 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 Open Watcom extended Windows 3.x executable or Dynamic Link Library

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 Open Watcom C/C++ Programmer's Guide or Open Watcom FORTRAN 77 Programmer's Guide for more information on creating specific types of applications.

Linking 16-bit x86 Executable Files

Linking 16-bit x86 DOS Executable Files

Linking 16-bit x86 DOS .COM Executable Files

Linking 16-bit x86 OS/2 Executable Files

Linking 16-bit x86 OS/2 Dynamic Link Libraries

Linking 16-bit x86 QNX Executable Files

Linking 16-bit x86 Windows 3.x Executable Files

Linking 16-bit x86 Windows 3.x Dynamic Link Libraries

Linking 32-bit x86 Executable Files

Linking 32-bit x86 CauseWay Executable Files

Linking 32-bit x86 CauseWay Dynamic Link Libraries

Linking 32-bit x86 DOS/4GW Executable Files

Linking 32-bit x86 PMODE/W Executable Files

Linking 32-bit x86 FlashTek Executable Files

Linking 32-bit x86 Novell NetWare Loadable Modules

Linking 32-bit x86 OS/2 Executable Files

Linking 32-bit x86 OS/2 Dynamic Link Libraries

Linking 32-bit x86 OS/2 Presentation Manager Executable Files

Linking 32-bit x86 Phar Lap Executable Files

Linking 32-bit x86 Phar Lap TNT Executable Files

Linking 32-bit x86 RDOS Executable Files

Linking 32-bit x86 RDOS Dynamic Link Libraries

Linking 32-bit x86 QNX Executable Files

Linking 32-bit x86 Extended Windows 3.x Executable

Linking 32-bit x86 Extended Windows 3.x Dynamic Link Libraries

Linking 32-bit x86 Windows 3.x or 9x Virtual Device Driver

Linking 32-bit x86 Windows 95 Executable Files

Linking 32-bit x86 Windows 95 Dynamic Link Libraries

Linking 32-bit x86 Windows NT Character-Mode Executable Files

Linking 32-bit x86 Windows NT Windowed Executable Files

Linking 32-bit x86 Windows NT Dynamic Link Libraries

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.

The ALIAS Directive

where

description

alias_name

is the alias name.

symbol_name

is the symbol name to which the alias name is mapped.

The ALIGNMENT Option

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 ANONYMOUSEXPORT Directive

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.

1. By default, the Open 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.

The AREA Option

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 ARTIFICIAL Option

The AUTOSECTION Directive

where

description

INTO

specifies that all overlays are to be placed into a file, namely ovl_file.  If "INTO" (short form "IN") is not specified, the overlays are placed in the executable file.

ovl_file

is the file specification for the name of an overlay file.  If no file extension is specified, a file extension of "ovl" is assumed.

The AUTOUNLOAD Option

The BEGIN Directive

The CACHE Option

The CASEEXACT Option

The CHECK Option

where

description

symbol_name

specifies the name of a procedure to execute before the NLM is unloaded.

The CHECKSUM Option

The # Directive

where

description

comment

is any sequence of characters.

The COMMIT Directive

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".

The COPYRIGHT Option

where

description

string

specifies the copyright information.

The CUSTOM Option

where

description

file_name

specifies the file name of the custom data file.

The CVPACK Option

The DEBUG Directive

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 ( dblist) 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 debugger.

• global symbol information
• line numbering information
• local symbol information
• typing information
• NetWare global symbol information

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.

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.

1. The debugging information is not present in the object files.
2. The "DEBUG" directive has been misplaced.

Line Numbering Information - DEBUG WATCOM LINES

Local Symbol Information - DEBUG WATCOM LOCALS

Typing Information - DEBUG WATCOM TYPES

All Debugging Information - DEBUG WATCOM ALL

Global Symbol Information

Global Symbols for the NetWare Debugger - DEBUG NOVELL

The ONLYEXPORTS Debugging Option

Using DEBUG Directives

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

Removing Debugging Information from an Executable File

The DESCRIPTION Option

where

description

string

is the sequence of characters to be embedded into the application or Dynamic Link Library.

The DISABLE Directive

where

description

msg_num

is a message number.  See the chapter entitled Open Watcom Linker Diagnostic Messages for a list of messages and their corresponding numbers.

The DISTRIBUTE Option

1. The symbols defined in the object module are not referenced by an ancestor of the overlay section selected to contain the object module.
2. At least one symbol in the object module is referenced by an immediate descendant of the overlay section selected to contain the module.

The DOSSEG Option

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"

The DYNAMIC Option

The ELIMINATE Option

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 Open 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 Open 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.

The END Directive

The ENDLINK Directive

The EXIT Option

where

description

symbol_name

specifies the name of the procedure that is executed when an NLM is unloaded.

The EXPORT Directive

EXPORT - OS/2, Win16, Win32 only

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.

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 the 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.  Note that the processor copies words rather than bytes and can copy up to 31 words.  Thus the number of bytes allowed is up to 62, and must be even.

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.

1. By default, the Open 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

EXPORT - ELF only

where

description

entry_name

is the name of the exported symbol.

1. By default, the Open 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').

EXPORT - Netware only

where

description

entry_name

is the name of the exported symbol.

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').

The FARCALLS Option

The FILE Directive

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 Open Watcom Linker.  Also, if you are running a DOS, OS/2 or Windows-hosted version of the Open Watcom Linker, the object file specification can contain wild cards (*, ?).  A file extension of "o" is assumed if you are running a UNIX-hosted version of the Open 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.

The FILLCHAR Option

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 FIXEDLIB Directive

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.

The FORCEVECTOR Directive

where

description

symbol_name

is a symbol name.

The FORMAT Directive

where

description

DOS

(short form "D") tells the Open 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 Open 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 Open 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.

ZDOS

(short form "ZD") tells the Open Watcom Linker to generate a ZDOS "EXE" file.
The name of the executable file will have extension "exe".  If "SYS", "HWD" or "FSD" is specified, a ZDOS driver file will be generated in which case the name of the executable file will have the extension "sys", "hwd" or "fsd".  Note that these default extensions can be overridden by using the "NAME" directive to name the executable file.

For more information on ZDOS executable file formats, see the chapter entitled ZDOS:  The ZDOS Executable File Format.

RAW

(short form "R") tells the Open Watcom Linker to generate a RAW output file.
If "HEX" is specified, a raw 32-bit output file in Intel Hex format with the extension "hex" will be created.  When "BIN" is specified or RAW is given without further specification, a raw 32-bit image with the extension "bin" will be created.  Note that these default extensions can be overridden by using the "NAME" directive to name the executable file.

A raw output file cannot contain debugging information.  If you wish to debug a raw file, you must use the "SYMFILE" option to instruct the Open Watcom Linker to place the debugging information in a separate file.

For more information on RAW executable file formats, see the chapter entitled RAW:  The RAW File Format.

WINDOWS

tells the Open 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 VXD

tells the Open Watcom Linker to generate a Windows VxD file (Virtual Device Driver).
The name of the file will have extension "386".  Note that this default extension can be overridden by using the "NAME" directive to name the driver file.

Specifying "DYNAMIC" (short form "DYN"), dynamicaly loadable driver will be generated (only for Windows 3.11 or 9x).  By default the Open Watcom Linker generate staticaly loadable driver (for Windows 3.x or 9x).

For more information on Windows Virtual Device Driver file format, see the chapter entitled WinVxD:  The Windows Virtual Device Driver File Format.

WINDOWS NT

tells the Open 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 Open 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 the CauseWay DOS extender, Tenberry Software's DOS/4G and DOS/4GW DOS extenders, and similar products.

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 Open 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 Open Watcom Linker to generate a NetWare 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 Open 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 Open Watcom Linker to generate a disk driver.  A file extension of "dsk" is used for the name of the executable file.

NAM

instructs the Open 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.

MSL

instructs the Open Watcom Linker to generate a Mirrored Server Link module.  The default file extension is "msl"

CDM

instructs the Open Watcom Linker to generate a Custom Device module.  The default file extension is "cdm"

HAM

instructs the Open Watcom Linker to generate a Host Adapter module.  The default file extension is "ham"

NLM

instructs the Open 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.

'number'

instructs the Open Watcom Linker to generate a specific type of NLM using 'number'.  This is a 32 bit value that corresponds to Novell allocated NLM types.
These are the current defined values:

0

Specifies a standard NLM (default extension .NLM)

1

Specifies a disk driver module (default extension .DSK)

2

Specifies a namespace driver module (default extension .NAM)

3

Specifies a LAN driver module (default extension .LAN)

4

Specifies a utility NLM (default extension .NLM)

5

Specifies a Mirrored Server Link module (default .MSL)

6

Specifies an Operating System module (default .NLM)

7

Specifies a Page High OS module (default .NLM)

8

Specifies a Host Adapter module (default .HAM)

9

Specifies a Custom Device module (default .CDM)

10

Reserved for Novell usage

11

Reserved for Novell usage

12

Specifies a Ghost module (default .NLM)

13

Specifies an SMP driver module (default .NLM)

14

Specifies a NIOS module (default .NLM)

15

Specifies a CIOS CAD type module (default .NLM)

16

Specifies a CIOS CLS type module (default .NLM)

21

Reserved for Novell NICI usage

22

Reserved for Novell NICI usage

23

Reserved for Novell NICI usage

24

Reserved for Novell NICI usage

25

Reserved for Novell NICI usage

26

Reserved for Novell NICI usage

27

Reserved for Novell NICI usage

28

Reserved for Novell NICI usage

description

is a textual description of the program being linked.

For more information on NetWare executable file formats, see the chapter entitled NetWare:  The NetWare O/S Executable File Format.

QNX

tells the Open 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.

RDOS

tells the Open Watcom Linker to generate a RDOS special executable file.
If "DEV" is specified, a device driver file is created.

If "BIN" is specified, a binary executable file is created.

If "MBOOT" is specified, a 16-bit multi-boot executable file is created.

The name of the executable file will have the extension "dev" for device driver or "bin" for binary or multi-boot executable.  Note that these default extensions can be overridden by using the "NAME" directive to name the executable file.

ELF

tells the Open 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.

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.

RDOS

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 RDOS executable will be created.

Linux

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 ELF executable will be created.

The FULLHEADER Option

1. This option may be useful when creating a 16-bit executable which is to be used as a stub program for a non-DOS executable.
2. This option is not required when using the Open Watcom Linker.  It is only needed when the non-DOS executable is created using a third-party linker which does not automatically extend the header size.

The HEAPSIZE Option

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.

Win32:

This parameter is ignored for DLL (zero is used).

The HELP Option

where

description

help_file

is the name of the help file.

The HSHIFT Option

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 IMPFILE Option

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 Open Watcom Library Manager.  If no file extension is specified, no file extension is assumed.

The IMPLIB Option

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.

The IMPORT Directive

IMPORT - OS/2, Win16, Win32 only

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.

1. By default, the Open 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').

IMPORT - ELF only

where

description

external_name

is the name of the external symbol.

1. By default, the Open 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').

IMPORT - Netware only

where

description

external_name

is the name of the external symbol.

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').

The @ Directive

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.

Win16 only:

We must also use the "EXPORT" directive to define the window function.  This is done using the following directive.
     
     export window_function

1. In the above example, we did not provide the file extension when the directive file was specified.  The Open 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.

The INCREMENTAL Option

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.

The INTERNALRELOCS Option

The LANGUAGE Directive

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).

The LARGEADDRESSAWARE Option

The LIBFILE Directive

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 Open Watcom Linker.  Also, if you are running a DOS, OS/2 or Windows-hosted version of the Open Watcom Linker, the object file specification can contain wild cards (*, ?).  A file extension of "o" is assumed if you are running a UNIX-hosted version of the Open 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).

1. When searching for an object or library file specified in a "LIBFILE" directive, the current working 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.

The LIBPATH Directive

where

description

path_name

is a path name.

The LIBRARY Directive

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.

Searching for Libraries Specified in Environment Variables

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"

1. If a library file specified in a "LIBRARY" directive contains an absolute path specification, the Open 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.

Converting Libraries Created using Phar Lap 386|LIB

The LINEARRELOCS Option

The LINKVERSION Option

The LONGLIVED Option

The MANGLEDNAMES Option

1. symbol name
2. scoping information
3. typing information

The MANYAUTODATA Option

Win16:

Note, however, that this attribute is not supported by Windows 3.x for 16-bit DLLs.

The MAP Option

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.

The MAXDATA Option

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 MAXERRORS Option

where

description

n

is the maximum number of error messages issued by the linker.

The MESSAGES Option

where

description

msg_file

is the name of the message file.

The MINDATA Option

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 MIXED1632 Option

The MODNAME Option

where

description

module_name

is the name of a Dynamic Link Library.

The MODFILE Directive

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 Open Watcom Linker.  Also, if you are running a DOS, OS/2 or Windows-hosted version of the Open Watcom Linker, the object file specification can contain wild cards (*, ?).  A file extension of "o" is assumed if you are running a UNIX-hosted version of the Open Watcom Linker.

The MODTRACE Directive

where

description

module_name

is the name of an object module defined in an object or library file.

The MODULE Directive

where

description

module_name

is the file name of a DLL or NLM.

The MULTILOAD Option

The NAME Directive

where

description

exe_file

is a file specification for the name of the executable file.  Under UNIX, or if the "NOEXTENSION" option was specified, no file extension is appended.  In all other cases, a file extension suitable for the current executable file format is appended if no file extension is specified.

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 UNIX-hosted version of the linker, or the "NOEXTENSION" option was specified, 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 UNIX-hosted version of the linker, or the "NOEXTENSION" option was used, an executable file called "test" will be generated.

The NAMELEN Option

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 NEWFILES Option

The NEWSEGMENT Directive

The NLMFLAGS Option

where

description

some_value

is an integer value that is OR'ed into the flags field of the header of the Netware executable.

The NOAUTODATA Option

The NODEFAULTLIBS Option

The NOEXTENSION Option

The NOINDIRECT Option

The NORELOCS Option

where

description

NORELOCS

tells the Open Watcom Linker not to generate relocation information.

The NOSTDCALL Option

The NOSTUB Option

The NOVECTOR Directive

where

description

symbol_name

is a symbol name.

1. If a function in section A calls a function in section B and section B is not an ancestor of section A, an overlay vector will be generated for the function in section B.  See the section entitled DOS:  Using Overlays for a description of ancestor.
2. If a global symbol's address is referenced (except by a direct call) and that symbol is defined in an overlay section, an overlay vector for that symbol will be generated.

The OBJALIGN Option

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 16 bytes and 256 megabytes inclusive.  The default is 64k.

The OLDLIBRARY Option

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.

The OFFSET Option

OFFSET - RAW only

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.

OFFSET - OS/2, Win32, ELF only

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.

OFFSET - PharLap only

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.

OFFSET - QNX only

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 ONEAUTODATA Option

Win16:

Note, however, that this attribute is not supported by Windows 3.x for 16-bit DLLs.

The OPTION Directive

where

description

option

is any of the linker options available for the executable format that is being generated.

The OPTLIB Directive

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.

Searching for Optional Libraries Specified in Environment Variables

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"

1. If a library file specified in a "OPTLIB" directive contains an absolute path specification, the Open Watcom Linker will not search any of the paths specified in the "LIB" environment string for the library file.  On UNIX platforms, 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.

The ORDER Directive

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.

class_name

is the name of a class defined in one or more object files.  If the class is not defined in an object file, the class_name and all associated options are ignored.  Note that the "ORDER" directive does not create classes or segments.  Classes specified with "CLNAME" keywords will be placed in the output image in the order listed.   Any classes that are not listed will be placed after the listed ones.

SEGADDR=n

(short form "SEGA") specifies the segment portion of the starting address of the class or segment in the output image.  It is combined with "OFFSET" to represent a unique linear address.  "SEGADDR" is only valid for segmented formats.  Its use in other contexts is undefined.  The "HSHIFT" value affects how the segment value is converted to a linear address.

OFFSET=n

(short form "OFF") specifies the offset portion of the starting address of the class or segment in the output image.   It is combined with "SEGADDR" to represent a unique linear address.  Offset is limited to a range of 0 to 65535 in segmented architectures, but can be a larger value for non-segmented architectures, up to the limits of the architecture.
When "SEGADDR" and/or "OFFSET" are specified, the location counter used to generate the executable is advanced to that address.  Any gaps are filled with the "FILLCHAR" value, except for HEX output format, in which case they are simply skipped.  If the location counter is already beyond the specified location, an error message is generated.  This would likely be the result of having specified classes or segments in incorrect order, or not providing enough room for preceding ones.  Without the "SEGADDR" and "OFFSET" options, classes and segments are placed in the executable consecutively, possibly with a small gap in between if required by the alignment specified for the class.  If "SEGADDR" is specified without corresponding "OFFSET", the offset portion of the address defaults to 0.

COPY

(short form "CO") indicates that the data from the segment named source_class_name is to be used in this segment.

NOEMIT

(short form "NOE") indicates that the data in this segment should not be placed in the executable.

SEGMENT

indicates the order of segments within a class, and possibly other options associated with that segment.  Segments listed are placed in the executable in the order listed.  They must be part of the class just named.  Any segments in that class not listed will follow the last listed segment.  The segment options are a subset of the class options and conform to the same specifications.

• Fix the program location
• Separate code and data to different fixed parts of memory
• Place a copy of initialized data in ROM (usually right after the code)
• Prevent the original of the initialized data from being written to the loadfile, since it resides in RAM and cannot be saved there.

The OSDOMAIN Option

The OSNAME Option

where

description

string

is any sequence of characters.

OS/2:

this is an OS/2 executable

Win16:

this is a Windows executable

Win32:

this is a Windows NT executable

The OSVERSION Option

The OUTPUT Directive

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.

RAW

specifies the output file to be a raw binary and will contain an absolute image of the executable's code and data.  Default file extension is "bin".

HEX

specifies the output file to contain a representation of the absolute image of the code and data using the Intel standard hex file format.  Default file extension is "hex".

OFFSET=n

(short form "OFF") specifies that linear addresses below n should be skipped when outputting the executable image.  This option does not affect address calculations and is intended to avoid unwanted padding when writing executable images that do not start at linear address zero.

HSHIFT

defines the relationship between segment values for type 02 records and linear addresses.  The value n is the number of digits to right shift a 32-bit value containing a segment address in its upper 16 bits in order to convert it to part of a linear address.  In more conventional terms, (16 - n ) is the amount to shift a segment value left in order to convert it to part of a linear address.

STARTREC

(short form "ST") specifies that a Starting Address record will be included in Intel Hex output.  This option is ignored if output type is not Intel hex.

The OVERLAY Directive

where

description

class

is the class name of the segments to be overlayed.

1. You should not specify a class in an "OVERLAY" directive that belongs to the group "DGROUP".  These classes are "BEGDATA", "DATA", "BSS" and "STACK".

The PACKCODE Option

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.

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.

The PACKDATA Option

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.

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.

The PATH Directive

where

description

path_name

is a path name.

The PRIVILEGE Option

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 PROTMODE Option

The PSEUDOPREEMPTION Option

The QUIET Option

The REDEFSOK Option

The REENTRANT Option

The REFERENCE Directive

where

description

symbol_name

is the symbol for which a reference is made.

The RESOURCE Directive

where

description

resource_file

is a file specification for the name of the resource file that to be added to the executable file.  If no file extension is specified, a file extension of "res" is assumed.

The RESOURCE Option

RESOURCE - OS/2, Win16, Win32 only

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.

RESOURCE - QNX only

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.

The RUNTIME Directive

RUNTIME - Win32 only

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.

RDOS

indicates that the application is a 32-bit RDOS application.

EFIBOOT

indicates that the application is a EFI boot application.

RUNTIME - PharLap only

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 Open 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 Open 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 Open 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 Open 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 Open 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 Open 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.

RUNTIME - ELF only

where

description

abi=abinum.abiversion

Specifying ABI/OS type and optional version indicates specific ABI that an ELF application is written for.  This information may affect how the ELF executable will be interpreted by the operating system.  If ABI version is not specified, zero will be used.  A list of official ABI types may be found in the System V Application Binary Interface specification.
For example, both of the following example indicate that the application requires Linux, but does not specify ABI version (numeric value zero).

     
     runtime linux
     runtime abiver=3.0

SVR4

indicates that the application is a generic ELF application conforming to the System V Release 4 ABI.  This is the default.

LINUX

(short form "LIN") indicates that the application is a Linux application.

FREEBSD

(short form "FRE") indicates that the application is a FreeBSD application.

NETBSD

(short form "NET") indicates that the application is a NetBSD application.

SOLARIS

(short form "SOL") indicates that the application is a Sun Solaris application.

ABIVER

(short form "ABI") specifies the numeric ABI type and optionally version.  This method allows specification of ABI types not explicitly supported by the Open Watcom Linker.

The RWRELOCCHECK Option

The SCREENNAME Option

where

description

name

specifies the screen name.

The SECTION Directive

where

description

INTO

specifies that the overlay is to be placed into a separate file, namely ovl_file.  If "INTO" (short form "IN") is not specified, the overlay is placed in the executable file.  Note that more than one overlay can be placed in the same file by specifying the same file name in multiple "SECTION" directives.

ovl_file

is the file specification for the name of an overlay file.  If no file extension is specified, a file extension of "ovl" is assumed.

The SEGMENT Directive

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, VxD 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, VxD 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 and VxD 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 and VxD 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 and VxD only) specifies that the segment requires I/O privilege.  That is, they can access the hardware directly.

NOIOPL

(short form "NOI", OS/2 and VxD 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 and VxD 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 Open 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 Open 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 and VxD only) specifies that the segment is discardable.  By default, segments are not discardable.

NONDISCARDABLE

(short form "NOND", VxD only) specifies that the segment is not discardable.  By default, segments are not discardable.

The SHARELIB Option

where

description

shared_nlm

is the file name of the shared NLM.

The SHOWDEAD Option

The SMALL Option

1. Your program has been compiled for a small code memory model.
2. You are creating an overlayed application.
3. The code in your program, including overlay areas, does not exceed 64K.

The SORT Directive

The STACK Option

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.

Note:

This parameter is ignored for DLL (zero is used).

The STANDARD Option

The START Option

where

description

symbol_name

specifies the name of the procedure where execution begins.

The STARTLINK Directive

The STATICS Option

The STUB Option

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 SYMFILE Option

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.

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.

The SYMTRACE Directive

where

description

symbol_name

is the name of a symbol.

The SYNCHRONIZE Option

The SYSTEM Directive

where

description

system_name

is a unique system name.

directive

is a linker directive.

where

description

system_name

is a defined system name.

where

description

system_name

is a defined system name.

Special System Names

• FORMAT
• LIBFILE
• LIBPATH
• LIBRARY
• NAME
• OPTION
• RUNTIME (for Phar Lap executable files only)
• SEGMENT (for OS/2 and QNX executable files only)

The THREADNAME Option

where

description

thread_name

specifies the pattern used for generating thread names and must be a string of 1 to 5 characters.

The TOGGLERELOCS Option

The UNDEFSOK Option

The VECTOR Directive

where

description

symbol_name

is a symbol name.

The VERBOSE Option

The VERSION Option

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.

The VFREMOVAL Option

The XDCDATA Option

where

description

rpc_file

is the name of the file containing RPC descriptions.

DOS:  The DOS Executable File Format

ALIAS alias_name=symbol_name{,alias_name=symbol_name}

AUTOSECTION

BEGIN {section_type [INTO ovl_file] {directive}} END

DEBUG dbtype [dblist] | DEBUG [dblist]

DISABLE msg_num{,msg_num}

ENDLINK

FILE obj_spec{,obj_spec}

FIXEDLIB library_file{,library_file}

FORCEVECTOR symbol_name{,symbol_name}

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

NOVECTOR symbol_name{,symbol_name}

OPTION option{,option}

AREA=n

ARTIFICIAL

[NO]CACHE

[NO]CASEEXACT

CVPACK

DISTRIBUTE

DOSSEG

DYNAMIC

ELIMINATE

[NO]FARCALLS

FULLHEADER

MANGLEDNAMES

MAP[=map_file]

MAXERRORS=n

NAMELEN=n

NODEFAULTLIBS

NOEXTENSION

NOINDIRECT

OSNAME='string'

PACKCODE=n

PACKDATA=n

QUIET

REDEFSOK

SHOWDEAD

SMALL

STACK=n

STANDARD

START=symbol_name

STATICS

SYMFILE[=symbol_file]

[NO]UNDEFSOK

VERBOSE

VFREMOVAL

OPTLIB library_file{,library_file}

OVERLAY class{,class}

PATH path_name{;path_name}

REFERENCE symbol_name{,symbol_name}

SECTION

SORT [GLOBAL] [ALPHABETICAL]

STARTLINK

SYMTRACE symbol_name{,symbol_name}

SYSTEM BEGIN system_name {directive} END

SYSTEM system_name

VECTOR symbol_name{,symbol_name}

# comment

@ directive_file

DOS:  Memory Layout

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"

DOS:  The Open Watcom Linker Memory Requirements

DOS:  Using Overlays

DOS:  Defining Overlay Structures

1. The root consists of file0 and file1.
2. Three overlays are defined.  The first overlay (overlay #1) contains file2, the second overlay (overlay #2) contains file3 and file4, and the third overlay (overlay #3) contains file5.

1. The 3 overlays are all loaded at the same memory location.  Such overlays are called parallel.

DOS:  The Dynamic Overlay Manager

DOS:  Nested Overlay Structures

1. The root contains file0 and file1.
2. Four overlays are defined.  The first overlay (overlay #1) contains file2, the second overlay (overlay #2) contains file3, the third overlay (overlay #3) contains file4 and file5, and the fourth overlay (overlay #4) contains file6.

1. Overlay #1 and overlay #2 are parallel overlays.  Overlay #3 and overlay #4 are also parallel overlays.
2. Overlay #3 and overlay #4 are loaded in memory following overlay #2.  In this case, overlay #2 is called an ancestor of overlay #3 and overlay #4.  Conversely, overlay #3 and overlay #4 are descendants of overlay #2.
3. The root is an ancestor of all overlays.

DOS:  Rules About Overlays

1. Care should be taken when passing addresses of functions as arguments.  Consider the following example.
   
        
        +-----------------------+<- start of root
        |                        |
        |         main           |
        |                        |
        +-----------+-----------+<- start of overlay
        |  modulea  |  moduleb  |   area
        |           |            |
        |     f     |     h      |
        |     g     |            |
        |           |            |
        +-----------+-----------+
   
   Function f passes the address of static function g to function h.  Function h then calls function g indirectly.  Function f and function g are defined in modulea and function h is defined in moduleb.  Furthermore, suppose that modulea and moduleb are parallel overlays.  The linker will not generate an overlay vector for function g since it is static so when function h calls function g indirectly, unpredictable results may occur.  Note that if g is a global function, an overlay vector will be generated and the program will execute correctly.
2. You should organize the overlay structure to minimize the number of times overlays have to be loaded into memory.  Consider a loop calling two routines, each routine in a different overlay.  If the overlay structure is such that the overlays are parallel, that is they occupy the same memory, each iteration of the loop will cause 2 overlays to be loaded into memory.  This will significantly increase execution time if the loop is iterated many times.
3. If a number of overlays have a number of common routines that they all reference, the common routines will most likely be placed in an ancestor overlay of the overlays that reference them.  For this reason, whenever an overlay is loaded, all its ancestors are also loaded.
4. In an overlayed program, the overlay loader is included in the executable file.  If we are dealing with relatively small programs, the size of the overlay loader may be larger than the amount of memory saved by overlaying the program.  In a larger application, the size of the overlayed version would be smaller than the size of the non-overlayed version.  Note that overlaying a program results in a larger executable file but the memory requirements are less.
5. The symbols "__OVLTAB__", "__OVLSTARTVEC__", "__OVLENDVEC__", "__LOVLLDR__", "__NOVLLDR__", "__SOVLLDR__", "__LOVLINIT__", "__NOVLINIT__" and "__SOVLINIT__" are defined when you use overlays.  Your program should not define these symbols.
6. When using the dynamic overlay manager, you should not take the address of static functions.  Static functions are not given overlay vectors, so if the module in which the address of a static function is taken, is moved by the dynamic overlay manager, that address will no longer point to the static function.

DOS:  Increasing the Dynamic Overlay Area

DOS:  How Overlay Files are Opened

DOS:  Converting Microsoft Response Files to Directive Files

ZDOS:  The ZDOS Executable File Format

ALIAS alias_name=symbol_name{,alias_name=symbol_name}

DEBUG dbtype [dblist] | DEBUG [dblist]

DISABLE msg_num{,msg_num}

ENDLINK

FILE obj_spec{,obj_spec}

FORMAT ZDOS [SYS | HWD | FSD]

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

[NO]FARCALLS

INCREMENTAL

MANGLEDNAMES

MAP[=map_file]

MAXERRORS=n

NAMELEN=n

NODEFAULTLIBS

NOEXTENSION

OSNAME='string'

QUIET

REDEFSOK

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

ZDOS:  Memory Layout

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"

ZDOS:  The Open Watcom Linker Memory Requirements

ZDOS:  Converting Microsoft Response Files to Directive Files

RAW:  The RAW File Format

ALIAS alias_name=symbol_name{,alias_name=symbol_name}

DEBUG dbtype [dblist] | DEBUG [dblist]

DISABLE msg_num{,msg_num}

ENDLINK

FILE obj_spec{,obj_spec}

FORMAT RAW [BIN | HEX]

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

[NO]FARCALLS

INCREMENTAL

MANGLEDNAMES

MAP[=map_file]

MAXERRORS=n

NAMELEN=n

NODEFAULTLIBS

NOEXTENSION

OFFSET=n

OSNAME='string'

QUIET

REDEFSOK

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