The following object module and library formats are supported:
|
The executable file formats supported by JWlink are:
|
JWlink binaries are available for the following operating systems:
We refer to the operating system upon which you run JWlink as the "host".
Chapter Linking Executable Files for Various Systems summarizes the most commonly used executable file formats that can be generated by the linker. The chapter entitled Linker Directives and Options describes all of the linker directives and options. The remaining chapters describe aspects of each of the executable file formats.
The JWlink command line format is:
jwlink {directive}
where directive is a series of JWlink directives specified on the command line or in one or more files. If the directives are contained within a file, the "@" character is used to reference that file. If no file extension is specified, a file extension of "lnk" is assumed.
Example:
jwlink name testprog @first @second option map
In the above example, directives are specified on the command line (e.g., "name testprog" and "option map") and in files (e.g., first.lnk and second.lnk).
To make JWlink display the available directives in full detail, enter;
jwlink ?
If jwlink is launched without any arguments at all, it will enter interactive mode, display prompt "JWLINK>" and wait for user input. You can then enter as many lines of directive information as required. Press "Ctrl/Z" followed by the "Enter" key to terminate the input of directive information if you are running a DOS, OS/2 or Windows NT-hosted version of JWlink. Press "Ctrl/D" to terminate the input of directive information if you are running a UNIX-hosted version of JWlink.
The sytem definitions listed below are defined in a special linker directive file, jwlink.lnk, consisting of editable plain ASCII text.
jwlink.lnk is automatically processed by JWlink before processing any other directives. On a DOS, OS/2, or Windows-hosted system, this file must be located in one of the paths specified in the PATH environment variable.
|
The default name of the linker directive file (jwlink.lnk) can be overridden by the JWLINK_LNK environment variable. If the specified file can't be opened, the default file name will be used. For example, if the JWLINK_LNK environment variable is defined as follows
set JWLINK_LNK=my.lnk
then JWlink will attempt to use a my.lnk directive file, and if that file cannot be opened, the linker will revert to using the default jwlink.lnk file.
In the following sections, we show some of the typical directives that you might use to create a particular executable file format. The common directives are described in the chapter entitled Linker Directives and Options. They are "common" in the sense that they may be used with any executable format. There are other, less general, directives that may be specified for a particular executable format. In each of the following sections, we refer you to chapters in which you will find more information on the directives available with the executable format used.
At this point, it should be noted that various systems have adopted particular executable file formats. For example, the CauseWay DOS extender, Tenberry Software DOS/4G(W) and FlashTek DOS extenders all support one of the OS/2 executable file formats. It is for this reason that you may find that we direct you to a chapter which would, at first glance, seem unrelated to the executable file format in which you are interested.
To summarize, the steps that you should follow to learn about creating a particular executable are:
To create a DOS 16-bit executable, there are 2 systems defined:
To create a DOS .EXE executable, use the following structure.
system dos
option map
name app_name
file obj1, obj2, ...
library lib1, lib2, ...
To create a DOS .COM executable, use the following structure.
system com
option map
name app_name
file obj1, obj2, ...
library lib1, lib2, ...
For more information, see the chapter entitled DOS Executable File Format.
To create this type of file, use the following structure.
system hx16
option map
name app_name
file obj1, obj2, ...
library lib1, lib2, ...
For more information, see the chapter entitled Win16 Executable and DLL File Formats.
To create this type of file, use the following structure.
system os2
option map
name app_name
file obj1, obj2, ...
library lib1, lib2, ...
For more information, see the chapter entitled OS/2 Executable and DLL File Formats.
To create this type of file, use the following structure.
system os2_dll
option map
name app_name
file obj1, obj2, ...
library lib1, lib2, ...
For more information, see the chapter entitled The OS/2 Executable and DLL File Formats.
To create this type of file, use the following structure.
system os2_pm
option map
name app_name
file obj1, obj2, ...
library lib1, lib2, ...
For more information, see the chapter entitled OS/2 Executable and DLL File Formats.
To create this type of file, use the following structure.
system win16
option map
name app_name
file obj1, obj2, ...
library lib1, lib2, ...
For more information, see the chapter entitled Win16 Executable and DLL File Formats.
To create this type of file, use the following structure.
system win16_dll
option map
name app_name
file obj1, obj2, ...
library lib1, lib2, ...
For more information, see the chapter entitled Win16 Executable and DLL File Formats.
To create this type of file, use the following structure.
system causeway
option map
name app_name
file obj1, obj2, ...
library lib1, lib2, ...
For more information, see the chapter entitled OS/2 Executable and DLL File Formats.
To create this type of file, use the following structure.
system cwdllr or cwdlls
option map
name app_name
file obj1, obj2, ...
library lib1, lib2, ...
For more information, see the chapter entitled OS/2 Executable and DLL File Formats.
To create this type of file, use the following structure.
system hx32
option map
name app_name
file obj1, obj2, ...
library lib1, lib2, ...
For more information, see the chapter entitled Win32/Win64 Executable and DLL File Formats.
To create this type of file, use the following structure.
system hx32_dll
option map
name app_name
file obj1, obj2, ...
library lib1, lib2, ...
For more information, see the chapter entitled Win32/Win64 Executable and DLL File Formats.
To create this type of file, use the following structure.
system hx32s
option map
name app_name
file obj1, obj2, ...
library lib1, lib2, ...
For more information, see the chapter entitled Win32/Win64 Executable and DLL File Formats.
To create this type of file, use the following structure.
system os2v2
option map
name app_name
file obj1, obj2, ...
library lib1, lib2, ...
For more information, see the chapter entitled OS/2 Executable and DLL File Formats.
To create this type of file, use the following structure.
system os2v2_dll
option map
name app_name
file obj1, obj2, ...
library lib1, lib2, ...
For more information, see the chapter entitled OS/2 Executable and DLL File Formats.
To create this type of file, use the following structure.
system os2v2_pm
option map
name app_name
file obj1, obj2, ...
library lib1, lib2, ...
For more information, see the chapter entitled OS/2 Executable and DLL File Formats.
There are two type of the Virtual Device Driver.
Staticaly loaded Virtual Device Driver used by Windows 3.x or 9x. To create this type of file, use the following structure.
system win_vxd
option map
name app_name
file obj1, obj2, ...
library lib1, lib2, ...
Dynamically loaded Virtual Device Driver used by Windows 3.11 or 9x. To create this type of file, use the following structure.
system win_vxd dynamic
option map
name app_name
file obj1, obj2, ...
library lib1, lib2, ...
For more information, see the chapter entitled Windows Virtual Device Driver File Format.
To create this type of file, use the following structure.
system pe_con
option map
name app_name
file obj1, obj2, ...
library lib1, lib2, ...
For more information, see the chapter entitled Win32/Win64 Executable and DLL File Formats.
To create this type of file, use the following structure.
system pe_gui
option map
name app_name
file obj1, obj2, ...
library lib1, lib2, ...
For more information, see the chapter entitled Win32/Win64 Executable and DLL File Formats.
To create this type of file, use the following structure.
system pe_dll
option map
name app_name
file obj1, obj2, ...
library lib1, lib2, ...
For more information, see the chapter entitled Win32/Win64 Executable and DLL File Formats.
JWlink supports a large set of directives and options. The following sections present these directives and options in alphabetical order. Not all directives and options are supported for all executable formats. When a directive or option applies only to a subset of the executable formats that the linker can generate, the supporting formats are noted. In the following example, the notation indicates that the directive or option is supported for all executable formats.
Example:
Formats: All
In the following example, the notation indicates that the directive or option is supported for OS/2, 16-bit Windows and 32-bit Windows executable formats only.
Example:
Formats: OS/2, Win16, Win32
Directives tell JWlink how to create your program. For example, using directives you can tell JWlink which object files are to be included in the program, which library files to search to resolve undefined references, and the name of the executable file.
The file jwlink.lnk is a special linker directive file that is automatically processed by JWlink before processing any other directives.
The default name of the linker directive file (jwlink.lnk) can be overridden by the JWLINK_LNK environment variable. If the specified file can't be opened, the default file name will be used. For example, if the JWLINK_LNK environment variable is defined as follows
set JWLINK_LNK=my.lnk
then JWlink will attempt to use a my.lnk directive file, and if that file cannot be opened, the linker will revert to using the default jwlink.lnk file.
It is also possible to use environment variables when specifying a directive. For example, if the LIBDIR environment variable is defined as follows,
set libdir=\test
then the linker directive
library %libdir%\mylib
is equivalent to the following linker directive.
library \test\mylib
Note that a space must precede a reference to an environment variable.
Many directives can take a list of one or more arguments separated by commas. Instead of a comma-delimited list, you can specify a space-separated list provided the list is enclosed in braces (e.g., { space delimited list }). For example, the FILE directive can take a list of object file names as an argument.
file first,second,third,fourth
The alternate way of specifying this is as follows.
file {first second third fourth}
Where this comes in handy is in make files, where a list of dependents is usually a space-delimited list.
OBJS = first second third fourth
.
.
.
jwlink file {$(objs)}
The following notation is used to describe the syntax of linker directives and options.
Certain characters have special meaning to the linker. When a special character must appear in a name, you can imbed the string that makes up the name inside apostrophes (e.g., 'name@8'). This prevents the linker from interpreting the special character in its usual manner. This is also true for file or path names that contain spaces (e.g., '\program files\software\mylib'). Normally, the linker would interpret a space or blank in a file name as a separator. The special characters are listed below:
|
The "#" directive is used to mark the start of a comment. All text from the "#" character to the end of the line is considered a comment. The format of the "#" directive is as follows.
# comment
where <comment> is any sequence of characters.
The following directive file illustrates the use of comments.
file main, trigtest
# Use my own version of "sin" instead of the
# library version.
file mysin
library \math\trig
@directive_var
or
@directive_file
The environment variable approach to specifying linker directives allows you to specify commonly used directives without having to specify them each time you invoke JWlink. If the environment variable "jwlink" is set as in the following example,
set jwlink=debug watcom all option map, verbose library math
jwlink @jwlink
then each time JWlink is invoked, full debugging information will be generated, a verbose map file will be created, and the library file "math.lib" will be searched for undefined references.
A linker directive file is useful, for example, when the linker input consists of a large number of object files and you do not want to type their names on the command line each time you link your program. Note that a linker directive file can also include other linker directive files.
Let the file "memos.lnk" be a directive file containing the following lines.
system my_os name memos file memos file actions file read file msg file prompt file memmgr library \termio\screen library \termio\keyboard
Consider the following example.
Example:
jwlink @memos
JWlink is instructed to process the contents of the directive file "memos.lnk". The executable image file will be called "memos.exe". The following object files will be loaded from the current directory.
memos.obj actions.obj read.obj msg.obj prompt.obj memmgr.obj
If any unresolved symbol references remain after all object files have been processed, the library files "screen.lib" and "keyboard.lib" in the directory "\termio" will be searched (in the order listed).
Notes:
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
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 ALIAS directive is used to specify an equivalent name for a symbol name. The format of the ALIAS directive ( short form A ) is as follows.
ALIAS alias_name=symbol_name{, alias_name=symbol_name}
Consider the following example.
alias sine=mysine
When the linker tries to resolve the reference to sine, it will immediately substitute the name mysine for sine and begin searching for the symbol mysine.
The ALIGNMENT option specifies the alignment for segments/sections in the executable file. The format of the ALIGNMENT option ( short form A ) is
OPTION ALIGNMENT=n
where <n> is a numeric value. The complete form of <n> is
[0x]d{d}[k|m]
d represents a decimal digit. If 0x is specified, the string of digits represents a hexadecimal number. If k is specified, the value is multiplied by 1024. If m is specified, the value is multiplied by 1024*1024.
<n> specifies the alignment for segments/sections in the executable file and must be a power of 2.
In 16-bit applications, segments in the executable file are pointed to by a segment table. An entry in the segment table contains a 16-bit value which is a multiple of the alignment value. Together they form the offset of the segment from the start of the segment table. Note that the smaller the value of <n> the smaller the executable file.
The default value of <n> depends on the format. For PE, the default value is 512. For the other formats, JWlink will automatically choose the smallest value of <n> possible ; hence in these cases you need not specify this option unless you want padding between segments in the executable file.
For alignment of sections in memory for flat formats, see the OBJALIGN option.
The ANONYMOUSEXPORT directive is an alternative to the EXPORT directive. The symbol associated with this name will not appear in either the resident or the non-resident names table. The entry point is, however, still available for ordinal linking.
The format of the ANONYMOUSEXPORT directive ( short form ANON ) is as follows.
ANONYMOUSEXPORT export{,export} or ANONYMOUSEXPORT =lbc_file export ::= entry_name[.ordinal][=internal_name]
++sym.dll_name[.[altsym].export_name][.ordinal]
All other librarian commands will be ignored.
Notes:
The AREA option can be used to set the size of the memory pool in which overlay sections are loaded by the dynamic overlay manager. The format of the AREA option ( short form AR ) is as follows.
OPTION AREA=n
[0x]d{d}[k|m]
d represents a decimal digit. If 0x is specified, the string of digits represents a hexadecimal number. If k is specified, the value is multiplied by 1024. If m is specified, the value is multiplied by 1024*1024.
The default size of the memory pool for a given application is selected by JWlink and is equal to twice the size of the largest overlay.
It is also possible to add to the memory pool at run-time. If you wish to add to the memory pool at run-time, see the section entitled DOS: Increasing the Dynamic Overlay Area.
The ARTIFICIAL option should only be used if you are developing a Open Watcom C++ application. A Open Watcom C++ application contains many compiler-generated symbols. By default, the linker does not include these symbols in the map file ( see the MAP option ). The ARTIFICIAL option can be used if you wish to include these compiler-generated symbols in the map file.
The format of the ARTIFICIAL option ( short form ART ) is:
OPTION ARTIFICIAL
The AUTOSECTION directive specifies that each object file that appears in a subsequent FILE directive, up to the next SECTION or END directive, will be assigned a different overlay. The AUTOSECTION method of defining overlays is most useful when using the dynamic overlay manager, selected by specifying the DYNAMIC option. For more information on the dynamic overlay manager, see the section entitled DOS: Using Overlays.
The format of the AUTOSECTION directive ( short form AUTOS ) is:
AUTOSECTION [INTO ovl_file]
Placing overlays in separate files has a number of advantages. For example, if your application was linked into one file, it may not fit on a single diskette, making distribution of your application difficult.
The AUTOUNLOAD option specifies that a NetWare Loadable Module (NLM) built with this option should automatically be unloaded when all of its entry points are no longer in use. This only applies if the NLM was automatically loaded by another modules loading.
The format of the AUTOUNLOAD option ( short form AUTOUN ) is:
OPTION AUTOUNLOAD
The BEGIN directive is used to define the start of an overlay area. An overlay area is a piece of memory in which overlays are loaded. All overlays defined between a BEGIN directive and the corresponding END directive are loaded into that overlay area.
The format of the BEGIN directive ( short form B ) is:
BEGIN
See Defining Overlay Structures how the BEGIN directive is supposed to be used.
The CACHE and NOCACHE options can be used to control caching of object and library files in memory by the linker. When neither CACHE nor NOCACHE is specified, the linker will only cache small libraries. Object files and large libraries are not cached. The CACHE and NOCACHE options can be used to alter this default behaviour. The CACHE option enables the caching of object files and large library files while the NOCACHE option disables all caching.
The format of the CACHE option ( short form CAC ) is:
OPTION CACHE
The format of the NOCACHE option ( short form NOCAC ) is:
OPTION NOCACHE
When linking large applications with many object files, caching object files will cause extensive use of memory by the linker. On virtual memory systems such as OS/2, Windows NT or Windows 95, this can cause extensive page file activity when real memory resources have been exhausted. This can degrade the performance of other tasks on your system. For this reason, the OS/2 and Windows-hosted versions of the linker do not perform object file caching by default. This does not imply that object file caching is not beneficial. If your system has lots of real memory or the linker is running as the only task on the machine, object file caching can certainly improve the performance of the linker.
On single-tasking environments such as DOS, the benefits of improved linker performance outweighs the memory demands associated with object file caching. For this reason, object file caching is performed by default on these systems. If the memory requirements of the linker exceed the amount of memory on your system, the NOCACHE option can be specified.
The QNX operating system is a multi-tasking real-time operating system. However, it is not a virtual memory system. Caching object files can consume large amounts of memory. This may prevent other tasks on the system from running, a problem that may be solved by using the NOCACHE option.
The CASEEXACT option tells JWlink to respect case when resolving references to global symbols. That is, "ScanName" and "SCANNAME" represent two different symbols. This is the default because the most commonly used languages (C, C++, FORTRAN) are case sensitive. The format of the CASEEXACT option ( short form C ) is:
OPTION CASEEXACT
It is possible to override the default by using the NOCASEEXACT option. The NOCASEEXACT option turns off case-sensitive linking. The format of the NOCASEEXACT option (short form NOCASE ) is:
OPTION NOCASEEXACT
The CHECK option specifies the name of a procedure to execute before an NLM is unloaded. This procedure can, for example, inform the operator that the NLM is in use and prevent it from being unloaded.
The format of the CHECK option ( short form CH ) is:
OPTION CHECK=symbol_name
If the CHECK option is not specified, no check procedure will be called.
The CHECKSUM option specifies that the linker should create an MS-CRC32 checksum for the current image. This is primarily used for DLL's and device drivers but can be applied to any PE format images. The format of the CHECKSUM option (no short form) is
OPTION CHECKSUM
When the operating system allocates the stack and heap for an application, it does not actually allocate the whole stack and heap to the application when it is initially loaded. Instead, only a portion of the stack and heap are allocated or committed to the application. Any part of the stack and heap that is not committed will be committed on demand.
The format of the COMMIT directive ( short form COM ) is:
COMMIT mem_type
mem_type ::= STACK=n | HEAP=n
where <n> represents a numeric value. The complete form of <n> is
[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 amount 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 default values for stack and heap commits are 4k. See the STACK and HEAPSIZE options for information on specifying reserved sizes for stack and heap.
The COPYRIGHT option specifies copyright information that is placed in the executable file. The format of the COPYRIGHT option ( short form COPYR ) is as follows.
OPTION COPYRIGHT 'string'
where <string> specifies the copyright information.
The format of the CUSTOM option ( short form CUST ) is as follows.
OPTION CUSTOM=file_name
where <file_name> specifies the file name of the custom data file.
The custom data file is placed into the executable file when the application is linked but is really not part of the program. When the application is loaded into memory, the information extracted from a custom data file is not loaded into memory. Instead, information is passed to the program (as arguments) which allows the access and processing of this information.
This option is only meaningful when generating Microsoft CodeView debugging information. This option causes the linker to automatically run the Open Watcom CodeView 4 Symbolic Debugging Information Compactor, CVPACK, on the executable that it has created. This is necessary to get the CodeView debugging information into a state where the Microsoft CodeView debugger will accept it.
The format of the CVPACK option ( short form CVP ) is:
OPTION CVPACK
For more information on generating CodeView debugging information into the executable, see the section entitled The DEBUG Directive
The DEBUG directive is used to tell JWlink to generate debugging information in the executable file. This extra information in the executable file is used by the Open Watcom Debugger. The format of the DEBUG directive ( short form D ) is as follows.
DEBUG dbtype [dblist] | DEBUG [dblist] dbtype ::= DWARF | WATCOM | CODEVIEW | NOVELL dblist ::= [db_option{,db_option}] db_option ::= LINES | TYPES | LOCALS | ALL DEBUG NOVELL only: db_option ::= ONLYEXPORTS | REFERENCED
JWlink supports four types of debugging information, DWARF (the default), WATCOM, CODEVIEW, or NOVELL.
DWARF short: 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: 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: 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: N | specifies a form of global symbol information that can only be processed by the NetWare debugger. |
The following options can be used with the DEBUG WATCOM directive to select specific types of debugging information to be included in the executable file:
LINES short: LI | specifies line numbering and global symbol information. |
LOCALS short: LO | specifies local and global symbol information. |
TYPES short: T | specifies typing and global symbol information. |
ALL short: A | specifies all of the above debugging information. |
ONLYEXPORTS short: ONL | restricts the generation of global symbol information to exported symbols. This option may only be used with Netware executable formats. |
The following options can be used with the DEBUG NOVELL directive to select specific types of debugging information to be included in the executable file:
ONLYEXPORTS short: ONL | restricts the generation of global symbol information to exported symbols. |
REFERENCED short: REF | restricts the generation of symbol information to referenced symbols only. |
The following sections describe the classes of debugging information.
The DEBUG WATCOM LINES option controls the processing of line numbering information. Line numbering information is the line number and address of the generated code for each line of source code in a particular module. This allows Open Watcom Debugger to perform source-level debugging. When JWlink encounters a DEBUG WATCOM directive with a LINES or ALL option, line number information for each subsequent object module will be placed in the executable file. This includes all object modules extracted from object files specified in subsequent FILE directives and object modules extracted from libraries specified in subsequent LIBRARY or FILE directives.
Note: If Open Watcom compilers are used, all modules for which line numbering information is requested must have been compiled with the "-d1" or "-d2" option.
The DEBUG WATCOM LOCALS option controls the processing of local symbol information. Local symbol information is the name and address of all symbols local to a particular module. This allows Open Watcom Debugger to locate these symbols so that you can reference local data and routines by name. When JWlink encounters a DEBUG WATCOM directive with a LOCALS or ALL option, local symbol information for each subsequent object module will be placed in the executable file. This includes all object modules extracted from object files specified in subsequent FILE directives and object modules extracted from libraries specified in subsequent LIBRARY or FILE directives.
Note: If Open Watcom compilers are used, all modules for which local symbol information is requested must have been compiled with the "-d2" option.
The DEBUG WATCOM TYPES option controls the processing of typing information. Typing information includes a description of all types, structures and arrays that are defined in a module. This allows Open Watcom Debugger to display variables according to their type. When JWlink encounters a DEBUG WATCOM directive with a TYPES or ALL option, typing information for each subsequent object module will be placed in the executable file. This includes all object modules extracted from object files specified in subsequent FILE directives and object modules extracted from libraries specified in subsequent LIBRARY or FILE directives.
Note: If Open Watcom compilers are used, all modules for which typing information is requested must have been compiled with the "-d2" option.
The DEBUG WATCOM ALL option specifies that LINES, LOCALS, and TYPES options are requested. The LINES option controls the processing of line numbering information. The LOCALS option controls the processing of local symbol information. The TYPES option controls the processing of typing information. Each of these options is described in a previous section. A subsequent DEBUG WATCOM directive without an ALL option discontinues those options which are not specified in the list of debug options.
Global symbol information consists of all the global symbols in your program and their address. This allows Open Watcom Debugger to locate these symbols so that you can reference global data and routines by name. When JWlink encounters a DEBUG directive, global symbol information for all the global symbols appearing in your program is placed in the executable file.
The NetWare operating system has a built-in debugger that can be used to debug programs. When DEBUG NOVELL is specified, JWlink will generate global symbol information that can be used by the NetWare debugger. Note that any line numbering, local symbol, and typing information generated in the executable file will not be recognized by the NetWare debugger. Also, the Open Watcom tool WSTRIP cannot be used to remove this form of global symbol information from the executable file.
The ONLYEXPORTS option ( short form ONL ) restricts the generation of global symbol information to exported symbols (symbols appearing in an EXPORT directive). If DEBUG WATCOM ONLYEXPORTS is specified, Open Watcom Debugger global symbol information is generated only for exported symbols. If DEBUG NOVELL ONLYEXPORTS is specified, NetWare global symbol information is generated only for exported symbols.
Consider the following directive file.
debug watcom all file module1 debug watcom lines file module2, module3 debug watcom library mylib
It specifies that the following debugging information is to be generated in the executable file.
Note that if the DEBUG WATCOM directive before the LIBRARY directive is not specified, line numbering information for all object modules extracted from the library "mylib.lib" would be generated in the executable file provided the object modules extracted from the library have line numbering information present.
Note: A DEBUG WATCOM directive with no option suppresses the processing of line numbering, local symbol and typing information for all subsequent object modules.
As you can see from the above example, the position of the DEBUG WATCOM directive is important when describing the debugging information that is to appear in the executable file.
Note: If you want all classes of debugging information for all files to appear in the executable file you must specify DEBUG WATCOM ALL before any FILE and LIBRARY directives.
For more information on this utility, see the chapter entitled "The Open Watcom Strip Utility" in the Open Watcom C/C++ Tools User's Guide or Open Watcom FORTRAN 77 Tools User's Guide.
The DESCRIPTION option inserts the specified text into the application or Dynamic Link Library. This is useful if you wish to embed copyright information into an application or Dynamic Link Library. The format of the DESCRIPTION option ( short form DE ) is:
OPTION DESCRIPTION 'string'
The DISABLE directive is used to disable the display of linker messages.
JWlink issues three classes of messages; fatal errors, errors and warnings. Each message has a 4-digit number associated with it. Fatal messages start with the digit 3, error messages start with the digit 2, and warning messages start with the digit 1. It is possible for a message to be issued as a warning or an error.
If a fatal error occurs, the linker will terminate immediately and no executable file will be generated.
If an error occurs, the linker will continue to execute so that all possible errors are issued. However, no executable file will be generated since these errors do not permit a proper executable file to be generated.
If a warning occurs, the linker will continue to execute. A warning message is usually informational and does not prevent the creation of a proper executable file. However, all warnings should eventually be corrected.
Note that the behaviour of the linker does not change when a message is disabled. For example, if a message that normally terminates the linker is disabled, the linker will still terminate but the message describing the reason for the termination will not be displayed. For this reason, you should only disable messages that are warnings.
The linker will ignore the severity of the message number. For example, some messages can be displayed as errors or warnings. It is not possible to disable the message when it is issued as a warning and display the message when it is issued as an error. In general, do not specify the severity of the message when specifying a message number.
The format of the DISABLE directive ( short form DISA ) is:
DISABLE msg_num{, msg_num}
The following DISABLE directive will disable message 28 (an undefined symbol has been referenced).
disable 28
The DISTRIBUTE option specifies that object modules extracted from library files are to be distributed throughout the overlay structure. The format of the DISTRIBUTE option ( short form DIS ) is as follows.
OPTION DISTRIBUTE
An object module extracted from a library file will be placed in the overlay section that satisfies the following conditions.
Note that libraries specified in the FIXEDLIB directive will not be distributed. Also, if a symbol defined in a library module is referenced indirectly (its address is taken), the module extracted from the library will be placed in the root unless the NOINDIRECT option is specified.
For more information on overlays, see the section entitled DOS: Using Overlays.
The DOSSEG option tells JWlink to order segments in a special way. The format of the DOSSEG option ( short form D ) is:
OPTION DOSSEG
When the DOSSEG option is specified, segments will be ordered in the following way.
+------------------------------------------------------------+ | segments not belonging to group DGROUP with class CODE | +------------------------------------------------------------+ | other segments not belonging to group DGROUP | +------------------------------------------------------------+ | segments of group DGROUP with class BEGDATA | +------------------------------------------------------------+ | segments of group DGROUP with class != BEGDATA, BSS, STACK | +------------------------------------------------------------+ | segments of group DGROUP with class BSS | +------------------------------------------------------------+ | segments of group DGROUP with class STACK | +------------------------------------------------------------+
A special segment belonging to class "BEGDATA" is defined when linking with Open Watcom run-time libraries. This segment is initialized with the hexadecimal byte pattern "01" and is the first segment in group "DGROUP" so that storing data at location 0 can be detected in segmented memory models.
Segments belonging to class "BSS" contain uninitialized data. Note that this only includes uninitialized data in segments belonging to group "DGROUP". Segments belonging to class "STACK" are used to define the size of the stack used for your application. Segments belonging to the classes "BSS" and "STACK" are last in the segment ordering so that uninitialized data need not take space in the executable file.
When using Open Watcom run-time libraries, it is not necessary to specify the DOSSEG option. One of the object files in the Open Watcom run-time libraries contains a special record that specifies the DOSSEG option.
If no DOSSEG option is specified, segments are ordered in the order they are encountered by JWlink.
When the DOSSEG option is specified, JWlink defines two special variables. _edata defines the start of the "BSS" class of segments and _end defines the end of the "BSS" class of segments. Your program must not redefine these symbols.
The DYNAMIC; option tells JWlink to use the dynamic overlay manager. The format of the DYNAMIC option ( short form DYN ) is as follows.
OPTION DYNAMIC
Note that the dynamic overlay manager can only be used with applications that have been compiled using the "of" option and a big code memory model. The "of" option generates a special prologue/epilogue sequence for procedures that is required by the dynamic overlay manager. See the compiler User's Guide for more information on the "of" option.
For more information on the dynamic overlay manager, see the section entitled DOS: Using Overlays.
The ELIMINATE option can be used to enable dead code elimination. Dead code elimination is a process the linker uses to remove unreferenced segments from the application. The linker will only remove segments that contain code; unreferenced data segments will not be removed.
The format of the ELIMINATE option ( short form EL ) is:
OPTION ELIMINATE
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.
The END directive is used to define the end of an overlay area. An overlay area is a piece of memory in which overlays are loaded. All overlays defined between a BEGIN directive and the corresponding END directive are loaded into that overlay area.
The format of the END directive ( short form E ) is as follows.
END
See Defining Overlay Structures how the END directive is supposed to be used.
The ENDLINK directive is used to indicate the end of a new set of linker commands that are to be processed after the current set of commands has been processed. The format of the ENDLINK directive ( short form ENDL ) is as follows.
ENDLINK
The STARTLINK directive is used to indicate the start of the set of commands.
The format of the EXIT option ( short form EX ) is:
OPTION EXIT=symbol_name
The default name of the exit procedure is "_Stop".
Note that the exit procedure cannot prevent the NLM from being unloaded. Once the exit procedure has executed, the NLM will be unloaded. The CHECK option can be used to specify a check procedure that can prevent an NLM from being unloaded.
The EXPORT directive is used to tell JWlink which symbols are available for import by other executables.
The EXPORT directive can be used to define the names and attributes of functions in Dynamic Link Libraries that are to be exported. An EXPORT definition must be specified for every Dynamic Link Library function that is to be made available externally.
The format of the EXPORT directive ( short form EXP ) is:
EXPORT export{,export} or EXPORT =lbc_file OS/2: export ::= entry_name[.ordinal][=internal_name] [PRIVATE] [NONAME | RESIDENT] [iopl_bytes] Win16: export ::= entry_name[.ordinal][=internal_name] [PRIVATE] [NONAME | RESIDENT] Win32/Win64: export ::= entry_name[.ordinal][=internal_name] [PRIVATE] [NONAME]
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.
++sym.dll_name[.[altsym].export_name][.ordinal]
All other librarian commands will be ignored.
Notes:
EXPORT entry_name RESIDENT
The EXPORT directive is used to tell JWlink which symbols are available for import by other executables. The format of the EXPORT directive ( short form EXP ) is:
EXPORT entry_name{,entry_name}
where <entry_name> is the name of the exported symbol.
Notes:
EXPORT entry_name{,entry_name}
where <entry_name> is the name of the exported symbol.
Notes:
The EXPORTALL option exports all global functions. Syntax is
OPTION EXPORTALL
The exported symbols are included in the symbol table of the resulting binary, which may significantly increase the binary size.
The FARCALLS option tells JWlink to optimize Far Calls. This is the default setting for JWlink. The format of the FARCALLS option ( short form FAR ) is as follows.
OPTION FARCALLS
The NOFARCALLS option turns off Far Calls optimization. The format of the NOFARCALLS option ( short form NOFAR ) is as follows.
OPTION NOFARCALLS
The FILE directive is used to specify the object files and library modules that JWlink is to process. The format of the FILE directive ( short form F ) is:
FILE obj_spec{,obj_spec}
obj_spec ::= obj_file[(obj_module)]
| library_file[(obj_module)]
Consider the following example.
Example:
jwlink system my_os f \math\sin, mycos
JWlink is instructed to process the following object files:
\math\sin.obj
mycos.obj
The object file "mycos.obj" is located in the current directory since no path was specified.
More than one FILE directive may be used. The following example is equivalent to the preceding one.
Example:
jwlink system my_os f \math\sin f mycos
Thus, other directives may be placed between lists of object files.
The FILE directive can also specify object modules from a library file or object file. Consider the following example.
Example:
jwlink system my_os f \math\math.lib(sin)
JWlink is instructed to process the object module "sin" contained in the library file "math.lib" in the directory "\math".
In the following example, JWlink will process the object module "sin" contained in the object file "math.obj" in the directory "\math".
Example:
jwlink system my_os f \math\math(sin)
In the following example, JWlink will include all object modules contained in the library file "math.lib" in the directory "\math".
Example:
jwlink system my_os f \math\math.lib
The FILLCHAR option ( short form FILL ) specifies the byte value used to fill gaps in the output image.
OPTION FILLCHAR=n
[0x]d{d}[k|m]
d represents a decimal digit. If 0x is specified, the string of digits represents a hexadecimal number. If k is specified, the value is multiplied by 1024. If m is specified, the value is multiplied by 1024*1024.
n specifies the value to be used in blank areas of the output image. The value must be in the range of 0 to 255, inclusive.
This option is most useful for raw binary output that will be programmed into an (E)EPROM where a value of 255 (0xff) is preferred. The default value of n is zero.
The FIXEDLIB directive can be used to explicitly place the modules from a library file in the overlay section in which the FIXEDLIB directive appears. The format of the FIXEDLIB directive (short form FIX ) is as follows.
FIXEDLIB library_file{,library_file}
Consider the following example.
begin
section file1, file2
section file3
fixedlib mylib
end
Two overlay sections are defined. The first contains file1 and file2. The second contains file3 and all modules contained in the library file "mylib.lib".
Note that all modules extracted from library files that appear in a LIBRARY directive are placed in the root unless the DISTRIBUTE option is specified.
The FORCEVECTOR directive forces JWlink to generate an overlay vector for the specified symbols. The format of the FORCEVECTOR directive ( short form FORCEVE ) is as follows.
FORCEVECTOR symbol_name{,symbol_name}
where <symbol_name> is a symbol name.
The FORMAT directive is used to specify the format of the executable file that JWlink is to generate. The format of this directive ( short form FORM ) is:
FORMAT form form ::= DOS [COM] | RAW [BIN | HEX] | WINDOWS [dll16_attrs] [MEMORY] [FONT] [DPMI] | WINDOWS VXD [DYNAMIC] | WINDOWS PE [TNT | HX] [dll32_attrs] | OS2 [dll16_attrs | os2_attrs] | OS2 FLAT | LE | LX [dll32_attrs | os2_attrs] | PHARLAP [EXTENDED | REX | SEGMENTED] | NOVELL [NLM | LAN | DSK | NAM | 'number'] 'description' | QNX [FLAT] | ELF [DLL] dll16_attrs ::= DLL [INITGLOBAL | INITINSTANCE] dll32_attrs ::= DLL [INITGLOBAL | INITINSTANCE] [TERMINSTANCE | TERMGLOBAL] os2_attrs ::= PM | PMCOMPATIBLE | FULLSCREEN | PHYSDEVICE | VIRTDEVICE
|
If no FORMAT directive is specified, the executable file format will be selected for each of the following host systems in the way described.
The FUZZYEXPORT option makes the linker search for mangled (aka "decorated") names if a symbol exported with the EXPORT directive cannot be found.
The format of the FUZZYEXPORT option ( short form FUZ ) is:
OPTION FUZZYEXPORT
Example:
A dll may contain 2 functions that are to be exported:
int __stdcall Function1( int var1, long varlong ); int __stdcall Function2( int var2 );
If option FUZZYEXPORT is not set, one has to tell the linker the decorated names:
jwlink format windows pe dll file test.obj export _Function1@8, _Function2@4
If option FUZZYEXPORT is set, one may use the unmangled names instead:
jwlink format windows pe dll file test.obj export Function1, Function2
Note that option FUZZYEXPORT works with cdecl ( '_'-prefix ) and stdcall ( '_'-prefix and '@nn'-suffix for functions ) naming conventions only. Also, if keyword __export ( or __declspec(dllexport)) is used within the source - and hence the EXPORT directive isn't necessary - the NOSTDCALL option is the better choice to get rid of name decorations.
The HEAPSIZE option specifies the size of the heap required by the application. The format of this option ( short form H ) is:
OPTION HEAPSIZE=n
where <n> represents a numeric value. The complete form of <n> is the following.
[0x]d{d}[k|m]
d represents a decimal digit. If 0x is specified, the string of digits represents a hexadecimal number. If k is specified, the value is multiplied by 1024. If m is specified, the value is multiplied by 1024*1024.
<n> specifies the size of the heap. The default heap size is 0x100000 (1 MB) for Win32/Win64 applications, else it is 0. The maximum value of <n> is 0x10000 (64 kB) for 16-bit applications and 4 GB for 32-bit applications which is the maximum size of a physical segment. Actually, for a particular application, the maximum value of <n> is 64K or 4G less the size of group "DGROUP".
For Win32/Win64, see the COMMIT directive for information on how to specify the committed size of the heap.
The HELP option specifies the file name of an internationalized help file whose language corresponds to the message file bound to this NLM.
The format of the HELP option ( short form HE ) is:
OPTION HELP=help_file
where <help_file> is the name of the help file.
The HSHIFT option defines the relationship between segment and linear address in a segmented executable. The format of the HSHIFT option is:
OPTION HSHIFT=n
where <n> represents a value. The complete form of <n> is the following.
d represents a decimal digit. If 0x is specified, the string of digits represents a hexadecimal number. If k is specified, the value is multiplied by 1024. If m is specified, the value is multiplied by 1024*1024.
<n> specifies the 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.
The HSHIFT option is useful for non-standard segmented architectures that have different alignment between segments and linear addresses, such as the IP cores by ARC, Inc. These cores support a 24-bit addressing mode where segment addresses are shifted 8 bits to form part of the linear address. The <n> value and its semantics match the analogous variable used by the compiler for computing addresses in the huge memory model.
The default value of <n> is 12, representing the 4-bit shift used in conventional x86 CPUs.
The IMPFILE option requests the linker to produce a command file for JWlib, the Library Manager. This file can be used to create an import library that corresponds to the DLL that is being generated. This option is useful in situations where JWlink cannot create an import library file when you have specified the IMPLIB option (i.e., the linker fails to launch JWlib, the Library Manager).
The format of the IMPFILE option ( short form IMPF ) is:
OPTION IMPFILE[=imp_file]
where <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.
By default, no command file is generated. Specifying this option causes the linker to generate an import library command file. The import library command file contains a list of the entry points in your DLL. When this command file is processed by the Open Watcom Library Manager, an import library file will be produced.
If no file name is specified, the import library command file will have a default file extension of "lbc" and the same file name as the DLL file. Note that the import library command file will be created in the same directory as the DLL file. The DLL file path and name can be specified in the NAME directive.
Alternatively, a library command file path and name can be specified. The following directive instructs the linker to generate a import library command file and call it "mylib.lcf" regardless of the name of the executable file.
option impfile=mylib.lcf
You can also specify a path and/or file extension when using the "IMPFILE=" form of the IMPFILE option.
The IMPLIB option requests the linker to produce an import library that corresponds to the DLL that is being generated. The format of the IMPLIB option ( short form IMPL ) is:
OPTION IMPLIB[=imp_lib]
where <imp_lib> is a file specification for the name of the import library file. If no file extension is specified, a file extension of ".lib" is assumed.
By default, no library file is generated. Specifying this option causes JWlink to generate an import library file. The import library file contains a list of the entry points in your DLL.
If no file name is specified, the import library file will have a default file extension of "lib" and the same file name as the DLL file. Note that the import library file will be created in the same directory as the DLL file. The DLL file path and name can be specified in the NAME directive.
Alternatively, a library file path and name can be specified. The following directive instructs the linker to generate a library file and call it "mylib.imp" regardless of the name of the executable file.
option implib=mylib.imp
You can also specify a path and/or file extension when using the "IMPLIB=" form of the IMPLIB option.
Note: Currently, to create the import library file, the linker spawns JWlib, the Library Manager. In case this fails, see the IMPFILE option.
The IMPORT directive is used to tell JWlink what symbols are defined externally in other executables.
The IMPORT directive describes a function that belongs to a Dynamic Link Library. The format of the IMPORT directive ( short form IMP ) is as follows.
IMPORT import{,import}
import ::= internal_name module_name[.entry_name | ordinal]
Notes:
The preferred method to resolve references to Dynamic Link Libraries is through the use of import libraries. See the sections entitled Using a Dynamic Link Library in OS/2, Using a Dynamic Link Library in Win16, or Using a Dynamic Link Library in Win32/Win64 for more information on import libraries.
The IMPORT directive is used to tell JWlink what symbols are defined externally in other executables. The format of the IMPORT directive ( short form IMP ) is as follows.
IMPORT external_name{,external_name}
Notes:
IMPORT external_name{,external_name}
Notes:
If an NLM contains external symbols, the NLMs that define the external symbols must be loaded before the NLM that references the external symbols is loaded.
The INCREMENTAL option can be used to enable incremental linking. Incremental linking is a process whereby the linker attempts to modify the existing executable file by changing only those portions for which new object files are provided.
The format of the INCREMENTAL option ( short form INC ) is:
OPTION INCREMENTAL[=inc_file_name]
This option engages the incremental linking feature of the linker. This option must be one of the first options encountered in the list of directives and options supplied to the linker. If the option is presented too late, the linker will issue a diagnostic message.
By default, the incremental information file has the same name as the program except with an "ilk" extension unless the NAME directive has not been seen yet. If this is the case then the file is called __jwlink.ilk.
The linker's incremental linking technique is very resistant to changes in the underlying object files - there are very few cases where an incremental re-link is not possible. The options ELIMINATE and VFREMOVAL cannot be used at the same time as incremental linking.
It is possible, over time, to accumulate unneeded functions in the executable by using incremental linking. To guarantee an executable of minimum size, you can cause a full relink by deleting the ".ilk" file or by not specifying the INCREMENTAL option.
Do not use a post processor like the Open Watcom Resource Compiler on the executable file since this will damage the data structures maintained by the linker. Add resources to the executable file using the RESOURCE option.
Note: Only DWARF debugging information is supported with incremental linking.
The INTERNALRELOCS option is used with LX format executables under 32-bit OS/2. By default, OS/2 executables do not contain internal relocation information and OS/2 Dynamic Link Libraries do contain internal relocation information. This option causes JWlink to include internal relocation information in OS/2 LX format executables.
The format of the INTERNALRELOCS option ( short form INT ) is:
OPTION INTERNALRELOCS
The KNOWEAS option may be used with MZ format executables. It makes JWlink reserve at least 0x40 bytes for the header, thus allowing to use the binary as a stub for other formats (NE, LE, PE). This option is only needed when the non-DOS executable is to be created by a third-party linker which does not automatically extend the header size.
The format of the KNOWEAS option is:
OPTION KNOWEAS
The LANGUAGE directive is used to specify the language in which strings in JWlink directives are specified. The format of the LANGUAGE directive ( short form LANG ) is:
LANGUAGE lang
lang ::= JAPANESE | CHINESE | KOREAN
The LARGEADDRESSAWARE option is used with PE format executables. This option will make JWlink set a flag in the PE header telling the OS that this application is able to handle a private address space of more than 2 GB. For PE32+ format executables (Win64), this is the default, hence this option has an effect for Win32 executables only.
The format of the LARGEADDRESSAWARE option ( short form LARGE ) is:
OPTION LARGEADDRESSAWARE
The LIBFILE directive is used to specify the object files that JWlink is to process. The format of this directive ( short form is LIBF ) is:
LIBFILE obj_spec{,obj_spec}
obj_spec ::= obj_file | library_file
The difference between the LIBFILE and the FILE directives is as follows.
Essentially, object files that appear in LIBFILE directives are viewed as components of a library that have not been explicitly placed in a library file.
Consider the following linker directive file.
libpath \libs libfile mystart path \objs file file1, file2
JWlink is instructed to process the following object files:
\libs\mystart.obj
\objs\file1.obj
\objs\file2.obj
Note that the executable file will have file name "file1" and not "mystart".
The LIBPATH directive is used to specify the directories that are to be searched for library files appearing in subsequent LIBRARY directives and object files appearing in subsequent LIBFILE directives. The format of the LIBPATH directive ( short form LIBP ) is:
LIBPATH [path_name{;path_name}]
where <path_name> is a path name.
Consider a directive file containing the following linker directives.
file test libpath \math library trig libfile newsin
First, JWlink will process the object file "test.obj" from the current working directory. The object file "newsin.obj" will then be processed, searching the current working directory first. If "newsin.obj" is not in the current working directory, the "\math" directory will be searched. If any unresolved references remain after processing the object files, the library file "trig.lib" will be searched. If the file "trig.lib" does not exist in the current working directory, the "\math" directory will be searched.
It is also possible to specify a list of paths in a LIBPATH directive. Consider the following example.
libpath \newmath;\math library trig
When processing undefined references, JWlink will attempt to process the library file "trig.lib" in the current working directory. If "trig.lib" does not exist in the current working directory, the "\newmath" directory will be searched. If "trig.lib" does not exist in the "\newmath" directory, the "\math" directory will be searched.
If the name of a library file appearing in a LIBRARY directive or the name of an object file appearing in a LIBFILE directive contains a path specification, only the specified path will be searched.
Note that
libpath path1 libpath path2
is equivalent to the following.
libpath path2;path1
The LIBRARY directive is used to specify the library files to be searched when unresolved symbols remain after processing all specified input object files. The format of the LIBRARY directive ( short form L ) is:
LIBRARY library_file{,library_file}
where <library_file> is a file specification for the name of a library file. If no file extension is specified, a file extension of "lib" is assumed.
Consider the following example.
Example:
jwlink system my_os file trig lib \math\trig, \cmplx\trig
JWlink is instructed to process the following object file:
trig.obj
If any unresolved symbol references remain after all object files have been processed, the following library files will be searched:
\math\trig.lib
\cmplx\trig.lib
More than one LIBRARY directive may be used. The following example is equivalent to the preceding one.
Example:
jwlink system my_os f trig lib \math\trig lib \cmplx\trig
Thus other directives may be placed between lists of library files.
The "LIB" environment variable can be used to specify a list of paths that will be searched for library files. The "LIB" environment variable can be set using the "set" command as follows:
set lib=\graphics\lib;\utility
Consider the following LIBRARY directive and the above definition of the "LIB" environment variable.
library \mylibs\util, graph
If undefined symbols remain after processing all object files specified in all FILE directives, JWlink will resolve these references by searching the following libraries in the specified order.
Notes:
jwlib newlib +pharlib.lib
The library file "pharlib.lib" is a library created using 386|LIB. The library file "newlib.lib" will be created so that JWlink can now process it.
The LINEARRELOCS option instructs the linker to generate offset fixups in addition to the normal segment fixups. The offset fixups allow the system to move pieces of code and data that were loaded at a particular offset within a segment to another offset within the same segment.
The format of the LINEARRELOCS option ( short form LI ) is:
OPTION LINEARRELOCS
The LINKVERSION option specifies that the linker should apply the given major and minor version numbers to the PE format image header. If a version number is not specified, then the built-in value of 2.18 is used. The format of the LINKVERSION option ( short form LINKV ) is as follows.
OPTION LINKVERSION = major[.minor]
The LONGLIVED option specifies that the application being linked will reside in memory, or be active, for a long period of time (e.g., background tasks). The memory manager, knowing an application is "LONGLIVED", allocates memory for the application so as to reduce fragmentation.
The format of the LONGLIVED option ( short form LO ) is as follows.
OPTION LONGLIVED
The MANGLEDNAMES option should only be used if you are developing a Open Watcom C++ application. Due to the nature of C++, the Open Watcom C++ compiler generates mangled names for symbols. A mangled name for a symbol includes the following.
This information is stored in a cryptic form with the symbol. When the linker encounters a mangled name in an object file, it formats the above information and produces this name in the map file.
If you would like the linker to produce the mangled name as it appeared in the object file, specify the MANGLEDNAMES option.
The format of the MANGLEDNAMES option ( short form MANG ) is:
OPTION MANGLEDNAMES
The MANYAUTODATA option specifies that a copy of the automatic data segment (default data segment defined by the group "DGROUP"), for the program module or Dynamic Link Library (DLL) being created, is made for each instance. The format of the MANYAUTODATA option ( short form MANY ) is as follows.
OPTION MANYAUTODATA
The default for a program module is MANYAUTODATA and for a Dynamic Link Library is ONEAUTODATA If you do not want the data area of a DLL to be shared across multiple applications, then you should specify OPTION MANYAUTODATA.
See the FORMAT directive for more information on the INITINSTANCE, TERMINSTANCE, INITGLOBAL and TERMGLOBAL DLL attributes.
The MAP option controls the generation of a map file. The format of this option ( short form M ) is:
OPTION MAP[=map_file]
where <map_file> is a file specification for the name of the map file. If no file extension is specified, a file extension of "map" is assumed.
By default, no map file is generated. Specifying this option causes JWlink to generate a map file. The map file is simply a memory map of your program. That is, it specifies the relative location of all global symbols in your program. The map file also contains the size of your program.
If no file name is specified, the map file will have a default file extension of "map" and the same file name as the executable file. Note that the map file will be created in the current directory even if the executable file name specified in the NAME directive contains a path specification.
Alternatively, a file name can be specified. The following directive instructs the linker to generate a map file and call it "myprog.map" regardless of the name of the executable file.
option map=myprog
You can also specify a path and/or file extension when using the "MAP=" form of the MAP option.
Other options and directives that may influence the contents of the map file:
The format of the "MAXDATA" option (short form "MAXD") is as follows.
OPTION MAXDATA=n
[0x]d{d}[k|m]
d represents a decimal digit. If 0x is specified, the string of digits represents a hexadecimal number. If k is specified, the value is multiplied by 1024. If m is specified, the value is multiplied by 1024*1024.
n specifies the maximum number of bytes, in addition to the memory required by executable image, that may be allocated by 386|DOS-Extender at the end of the loaded executable image. No more than n bytes will be allocated.
If the MAXDATA option is not specified, a default value of hexadecimal ffffffff is assumed. This means that 386|DOS-Extender will allocate all available memory to the program at load time.
The MAXERRORS option can be used to set a limit on the number of error messages generated by the linker. Note that this does not include warning messages. When this limit is reached, the linker will issue a fatal error and terminate.
The format of the MAXERRORS option ( short form MAXE ) is as follows.
OPTION MAXERRORS=n
The MESSAGES option specifies the file name of an internationalized message file that contains the default messages for the NLM. This is the name of the default message file to load for NLMs that are enabled. Enabling allows the same NLM to display messages in different languages by switching message files.
The format of the MESSAGES option ( short form MES ) is as follows.
OPTION MESSAGES=msg_file
The format of the MINDATA option ( short form MIND ) is:
OPTION MINDATA=n
[0x]d{d}[k|m]
d represents a decimal digit. If 0x is specified, the string of digits represents a hexadecimal number. If k is specified, the value is multiplied by 1024. If m is specified, the value is multiplied by 1024*1024.
n specifies the minimum number of bytes, in addition to the memory required by executable image, that must be allocated by 386|DOS-Extender at the end of the loaded executable image. If n bytes are not available, the program will not be executed.
If the MINDATA option is not specified, a default value of zero is assumed. This means that 386|DOS-Extender will load the program as long as there is enough memory for the load image; no extra memory is required.
The MIXED1632 option specifies that 16-bit and 32-bit logical segments may be grouped into a single physical segment. This applies to both code and data segments.
The format of the MIXED1632 option ( short form MIX ) is as follows.
OPTION MIXED1632
This option is useful certain specialized applications, such as OS/2 physical device drivers. In most cases, mixing of 16-bit and 32-bit segments should be avoided.
The MODNAME option specifies a name to be given to the module being created. The format of the MODNAME option ( short form MODN ) is:
OPTION MODNAME=module_name
where <module_name> is the name of a Dynamic Link Library.
Once a module has been loaded (whether it be a program module or a Dynamic Link Library), <mod_name> is the name of the module known to the operating system. If the MODNAME option is not used to specify a module name, the default module name is the name of the executable file without the file extension.
The MODFILE directive instructs the linker that only the specified object files have changed. The format of the MODFILE directive ( short form MODF ) is:
MODFILE obj_file{,obj_file}
where <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 JWlink. Also, if you are running a DOS, OS/2 or Windows-hosted version of JWlink, the object file specification can contain wild cards (*, ?). A file extension of "o" is assumed if you are running a UNIX-hosted version of JWlink.
This directive is used only in concert with incremental linking. This directive tells the linker that only the specified object files have changed. When this option is specified, the linker will not check the dates on any of the object files or libraries when incrementally linking.
The MODTRACE directive instructs JWlink to print a list of all modules that reference the symbols defined in the specified modules. The format of this directive ( short form MODT ) is:
MODTRACE module_name{,module_name}
where <module_name> is the name of an object module defined in an object or library file.
The information is displayed in the map file ( see the MAP option ).
Example:
jwlink system my_os op map file test lib math modt trig
If the module "trig" defines the symbols "sin" and "cos", JWlink will list, in the map file, all modules that reference the symbols "sin" and "cos".
Also see the SYMTRACE directive.
The MODULE directive is used to specify the DLLs or NLMs to be loaded before this executable is loaded. The format of the MODULE directive ( short form MODU ) is:
MODULE module_name{,module_name}
The MULTILOAD option specifies that the module can be loaded more than once by a "load" command. The format of the MULTILOAD option ( short form MULTIL ) is:
OPTION MULTILOAD
If the MULTILOAD option is not specified, it will not be possible to load the module more than once using the "load" command.
The NAME directive is used to provide a name for the executable file generated by JWlink. The format of the NAME directive ( short form is N ) is:
NAME exe_file
where <exe_file> specifies 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.
Example:
jwlink system my_os name myprog file test, test2, test3
Here the linker is instructed to generate an executable file called "myprog.exe" if you are running a DOS, OS/2 or Windows-hosted version of the linker. If you are running a UNIX-hosted version of the linker, or the NOEXTENSION option was specified, an executable file called "myprog" will be generated.
Notes:
The NAMELEN option tells JWlink to limit the significant characters of symbols.
The format of this option ( short form NAMEL ) is:
OPTION NAMELEN=n
where <n> is a numeric value. The complete form of <n> is:
[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 number of significant characters for any symbol will be restricted to <n>. If the significant part of any global symbol is not unique, a warning or error message will be issued, depending on the [NO]REDEFSOK option.
Some computer systems, for example, require that all global symbols be uniquely identified in 8 characters. By specifying an appropriate value for the NAMELEN option, you can ease the task of porting your application to other computer systems.
The NEWFILES option specifies that the application uses the high-performance file system. This option is applicable to 16-bit OS/2 applications only. The format of the NEWFILES option ( short form NEWF ) is:
OPTION NEWFILES
This directive is intended for 16-bit segmented applications. By default, JWlink automatically groups logical code segments into physical segments. By default, these segments are 64K bytes in size. However, the PACKCODE option can be used to specify a maximum size for all physical segments that is smaller than 64K bytes.
The NEWSEGMENT directive provides an alternate method of grouping code segments into physical segments. By placing this directive after a sequence of FILE directives, all code segments appearing in object modules specified by the sequence of FILE directives will be packed into a physical segment. Note that the size of a physical segment may vary in size. The format of the NEWSEGMENT directive ( short form NEW ) is as follows.
NEWSEGMENT
Consider the following example.
file file1, file2, file3 newsegment file file4 file file5
Code segments from file1, file2 and file3 will be grouped into one physical segment. Code segments from file4 and file5 will be grouped into another physical segment.
Note that code segments extracted from library files will be grouped into physical segments as well. The size of these physical segments is determined by the PACKCODE option and is 64k by default.
The NLMFLAGS option is used to set bits in the flags field of the header of the Netware executable file. The format of the NLMFLAGS option ( short form NLMF ) is as follows.
OPTION NLMFLAGS=some_value
The NOAUTODATA option specifies that no automatic data segment (default data segment defined by the group "DGROUP"), exists for the program module or Dynamic Link Library being created. This option applies to 16-bit applications only. The format of the NOAUTODATA option ( short form NOA ) is:
OPTION NOAUTODATA
Special object module records that specify default libraries are placed in object files generated by Open Watcom compilers. These libraries reflect the memory and floating-point model that a source file was compiled for and are automatically searched by JWlink when unresolved symbols are detected. These libraries can exist in the current directory, in one of the paths specified in LIBPATH directives, or in one of the paths specified in the LIB environment variable.
Note that all library files that appear in a LIBRARY directive are searched before default libraries. The NODEFAULTLIBS option instructs JWlink to ignore default libraries. That is, only libraries appearing in a LIBRARY directive are searched.
The format of the NODEFAULTLIBS option ( short form NOD ) is:
OPTION NODEFAULTLIBS
The NOEXTENSION option suppresses automatic addition of an extension to the name of the executable file generated by JWlink. This affects both names specified explicitly through the NAME directive as well as default names chosen in the absence of a NAME directive.
The format of the NOEXTENSION option ( short form NOEXT ) is:
OPTION NOEXTENSION
The NOINDIRECT option suppresses the generation of overlay vectors for symbols that are referenced indirectly (their address is taken) when the module containing the symbol is not an ancestor of at least one module that indirectly references the symbol. This can greatly reduce the number of overlay vectors and is a safe optimization provided there are no indirect calls to these symbols. If, for example, the set of symbols that are called indirectly is known, you can use the "VECTOR" option to force overlay vectors for these symbols.
The format of the NOINDIRECT option ( short form NOI ) is:
OPTION NOINDIRECT
For more information on overlays, see the section entitled DOS: Using Overlays.
The NOLARGEADDRESSAWARE option ( short form NOLARGE ) is used with PE format executables. This option will make JWlink set a flag in the PE header telling the OS that this application cannot handle an address space of more than 2 GB. For Win32 binaries, this is the default setting, hence this option will have an effect for Win64 binaries only.
The format of the NOLARGEADDRESSAWARE option is:
OPTION NOLARGEADDRESSAWARE
The NORELOCS option ( short form NOR ) specifies that no relocation information is to be written to the executable file.
The format of this option is:
OPTION NORELOCS
QNX only: when the NORELOCS option is specified, the executable file can only be run in protected mode and will not run in real mode. In real mode, the relocation information is required; in protected mode, the relocation information is not required unless your application is running at privilege level 0.
The NOSTDCALL option specifies that the characters unique to the __stdcall calling convention be trimmed from all of the symbols that are exported from the DLL being created. The format of the NOSTDCALL option ( short form NOSTDC ) is:
OPTION NOSTDCALL
Considering the following declarations.
Example:
short PASCAL __export Function1( short var1, long varlong, short var2 ); short PASCAL __export Function2( long varlong, short var2 )
Under ordinary circumstances, these __stdcall symbols are mapped to "_Function1@12" and "_Function2@8" respectively. The "@12" and "@8" reflect the number of bytes in the argument list (short is passed as int). When the NOSTDCALL option is specified, these symbols are stripped of the "_" and "@xx" adornments. Thus they are exported from the DLL as "Function1" and "Function2".
This option makes it easier to access functions exported from DLLs, especially when using other software languages such as FORTRAN which do not add on the __stdcall adornments.
Note: Use the IMPLIB option to create an import library for the DLL which can be used with software languages that add on the __stdcall adornments.
The NOSTUB option specifies that no "stub" program is to be placed at the beginning of the executable file being generated. The format of the NOSTUB option is:
OPTION NOSTUB
This option is helpful in cases when the executable file being generated cannot be directly executed by the user, such as a device driver, and hence the stub program would be redundant.
The NOVECTOR directive forces JWlink to not generate an overlay vector for the specified symbols. The format of the NOVECTOR directive ( short form NOV ) is as follows.
NOVECTOR symbol_name{,symbol_name}
The linker will create an overlay vector in the following cases.
Note that in the latter case, more overlay vectors may be generated that necessary. Suppose section A contains three global functions, f, g and h. Function f passes the address of function g to function h who can then calls function g indirectly. Also, suppose function g is only called from sections that are ancestors of section A. The linker will generate an overlay vector for function g even though none is required. In such a case, the "NOVECTOR" directive can be used to remove the overhead associated with calling a function through an overlay vector.
The NXCOMPAT option is used with PE format executables. A flag in the PE header is set to tell the OS that the binary is compatible with data execution prevention (DEP).
The format of the NXCOMPAT option ( short form NXC ) is:
OPTION NXCOMPAT
The OBJALIGN option ( short form OBJA ) specifies the alignment for objects in memory. The format of this option is:
OPTION OBJALIGN=n
where <n> represents a numeric value. The complete form of <n> is
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 value of <n> is 4k for PE, ELF and WinVxD, else it is 64k.
For alignment of objects in the image file, see the ALIGNMENT Option.
The OLDLIBRARY option is used to preserve the export ordinals for successive versions of a Dynamic Link Library. This ensures that any application that references functions in a Dynamic Link Library by ordinal will continue to execute correctly. The format of the OLDLIBRARY option ( short form OLD ) is:
OPTION OLDLIBRARY=dll_name
where <dll_name> is a file specification for the name of a Dynamic Link Library. If no file extension is specified, a file extension of "DLL" is assumed.
Only the current directory or a specified directory will be searched for Dynamic Link Libraries specified in the OLDLIBRARY option.
The OFFSET option specifies the linear base address of the raw output image.
The format of the OFFSET option ( short form OFF ) is:
OPTION OFFSET=n
d represents a decimal digit. If 0x is specified, the string of digits represents a hexadecimal number. If k is specified, the value is multiplied by 1024. If m is specified, the value is multiplied by 1024*1024.
<n> specifies the offset at which the output image will be located.
Example:
option offset=0xc0000000
The image will be virtually/physically located to the linear address 0xc0000000.
The OFFSET option specifies the preferred base linear address at which the executable or DLL will be loaded.
The format of the OFFSET option ( short form OFF ) is:
OPTION OFFSET=n
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.
If the operating system is unable to load the application at the specified base linear address, it will load it at a different location which will increase the load time since a relocation phase must be performed.
The default base linear address is 0x10000 for OS/2 executables, 0x400000 for Win32/Win64 applications and 0x10000000 for Win32/Win64 DLLs. For ELF, the default base address depends on the CPU architecture.
This option is most useful for improving the load time of DLLs, especially for an application that uses multiple DLLs.
The OFFSET option specifies the offset in the program's segment in which the first byte of code or data is loaded.
The format of the OFFSET option ( short form OFF ) is:
OPTION OFFSET=n
d represents a decimal digit. If 0x is specified, the string of digits represents a hexadecimal number. If k is specified, the value is multiplied by 1024. If m is specified, the value is multiplied by 1024*1024.
<n> specifies the offset (in bytes) at which the program is loaded and must be a multiple of 4K. JWlink will round the value up to a multiple of 4K if it is not already a multiple of 4K.
It is possible to detect NULL pointer references by linking the program at an offset which is a multiple of 4K. Usually an offset of 4K is sufficient.
Example:
option offset=4k
When the program is loaded by 386|DOS-Extender, the pages skipped by the OFFSET option are not mapped. Any reference to an unmapped area (such as a NULL pointer) will cause a page fault preventing the NULL reference from corrupting the program.
The OFFSET option specifies the offset in the program's segment in which the first byte of code or data is loaded. This option does not apply to 16-bit QNX applications.
The format of the OFFSET option ( short form OFF ) is:
OPTION OFFSET=n
d represents a decimal digit. If 0x is specified, the string of digits represents a hexadecimal number. If k is specified, the value is multiplied by 1024. If m is specified, the value is multiplied by 1024*1024.
<n> specifies the offset (in bytes) at which the program is loaded and must be a multiple of 4K. JWlink will round the value up to a multiple of 4K if it is not already a multiple of 4K. The following describes a use of the OFFSET option.
It is possible to detect NULL pointer references by linking the program at an offset which is a multiple of 4K. Usually an offset of 4K is sufficient.
Example:
option offset=4k
When the program is loaded, the pages skipped by the OFFSET option are not mapped. Any reference to an unmapped area (such as a NULL pointer) will cause a page fault preventing the NULL reference from corrupting the program.
The ONEAUTODATA option specifies that the automatic data segment (default data segment defined by the group "DGROUP"), for the program module or Dynamic Link Library (DLL) being created, will be shared by all instances. The format of the ONEAUTODATA option ( short form ONE ) is:
OPTION ONEAUTODATA
The default for a Dynamic Link Library is ONEAUTODATA and for a program module is MANYAUTODATA. If you do not want the data area of a DLL to be shared across multiple applications, then you should specify OPTION MANYAUTODATA.
See the FORMAT directive for more information on the INITINSTANCE, TERMINSTANCE, INITGLOBAL and TERMGLOBAL DLL attributes.
The OPTION directive ( short form OP ) is used to specify options to JWlink. The format of this directive is:
OPTION option{,option}
where <option> is any of the linker options available for the executable format that is being generated.
The OPTLIB directive is used to specify the library files to be searched when unresolved symbols remain after processing all specified input object files. The format of the OPTLIB directive (no short form) is as follows.
OPTLIB library_file{,library_file}
This directive is similar to the LIBRARY directive except that the linker will not issue a warning message if the library file cannot be found.
Consider the following example.
Example:
jwlink system my_os file trig optlib \math\trig, \cmplx\trig
JWlink is instructed to process the following object file:
trig.obj
If any unresolved symbol references remain after all object files have been processed, the following library files will be searched:
\math\trig.lib
\cmplx\trig.lib
More than one OPTLIB directive may be used. The following example is equivalent to the preceding one.
Example:
jwlink system my_os f trig optlib \math\trig optlib \cmplx\trig
Thus other directives may be placed between lists of library files.
The "LIB" environment variable can be used to specify a list of paths that will be searched for library files. The "LIB" environment variable can be set using the "set" command as follows:
set lib=\graphics\lib;\utility
Consider the following "OPTLIB" directive and the above definition of the "LIB" environment variable.
optlib \mylibs\util, graph
If undefined symbols remain after processing all object files specified in all "FILE" directives, JWlink will resolve these references by searching the following libraries in the specified order.
Notes:
The ORDER directive is used to specify the order in which classes are placed into the output image, and the order in which segments are linked within a class. The directive can optionally also specify the starting address of a class or segment, control whether the segment appears in the output image, and facilitate copying of data from one segment to another. The ORDER Directive is primarily intended for embedded (ROMable) targets that do not run under an operating system, or for other special purpose applications. The format of the ORDER directive ( short form ORD ) is:
ORDER {CLNAME class_name [class_options]}+ class_options ::= [SEGADDR=n][OFFSET=n][copy_option][NOEMIT]{seglist} copy_option ::= [COPY source_class_name] seglist := {SEGMENT seg_name [SEGADDR=n][OFFSET=n][NOEMIT]}+
[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.
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.
In ROM-based applications it is often necessary to:
The ORDER directive caters for these requirements. Classes can be placed in the executable in a specific order, with absolute addresses specified for one or more classes, and segments within a class can be forced into a specified order with absolute addresses specified for one or more of them. Initialized data can be omitted at its target address, and a copy included at a different address.
Following is a sample ORDER directive for an embedded target (AM186ER). The bottom 32K of memory is RAM for data. A DGROUP starting address of 0x80:0 is required. The upper portion of memory is FLASH ROM. Code starts at address 0xD000:0. The initialized data from DGROUP is placed immediately after the code.
order clname BEGDATA NOEMIT segaddr=0x80 segment _NULL segment _AFTERNULL clname DATA NOEMIT segment _DATA clname BSS clname STACK clname START segaddr=0xD000 clname CODE segment BEGTEXT segment _TEXT clname ROMDATA COPY BEGDATA clname ROMDATAE
DGROUP consists of classes "BEGDATA", "DATA", "BSS", "BSS2" and "STACK". Note that these are marked "NOEMIT" (except for the BSS classes and STACK which are not initialized, and therefore have no data in them anyway) to prevent data from being placed in the loadfile at 0x80:0. The first class of DGROUP is given the fixed starting segment address of 0x80 (offset is assumed to be 0). The segments "_NULL", "_AFTERNULL" and "_DATA" will be allocated consecutively in that order, and because they are part of DGROUP, will all share the same segment portio of the address, with offsets adjusted accordingly.
The code section consists of classes "START" and "CODE". These are placed beginning at 0xD000:0. "START" contains only one segment, which will be first. It will have a CS value of 0xD000. Code has two segments, "BEGTEXT" and "_TEXT" which will be placed after "START", in that order, and packed into a single CS value of their own (perhaps 0xD001 in this example), unless they exceed 64K in size, which should not be the case if the program was compiled using the small memory model.
The classes "ROMDATA" and "ROMDATAE" were created in assembly with one segment each and no symbols or data in them. The class names can be used to identify the beginning and end of initialized data so it can be copied to RAM by the startup code.
The "COPY" option actually works at the group level, because that is the way it is generally needed. The entire data is in DGROUP. "ROMDATA" will be placed in a group of its own called "AUTO". (Note: each group mentioned in the map file under the name "AUTO" is a separate group. They are not combined or otherwise related in any way, other than they weren't explicitly created by the programmer, compiler or assembler, but rather automatically created by the linker in the course of its work.) Therefore there is a unique group associated with this class. The "COPY" option finds the group associated with "BEGDATA" and copies all the object data from there to "ROMDATA". Specifically, it places a copy of this data in the executable at the location assigned to "ROMDATA", and adjusts the length of "ROMDATA" to account for this. All symbol references to this data are to its execution address (0x80:0), not where it ended up in the executable (for instance 0xD597:0). The starting address of "ROMDATAE" is also adjusted to account for the data assigned to "ROMDATA". That way, the program can use the symbol "ROMDATAE" to identify the end of the copy of DGROUP. It is also necessary in case more than one "COPY" class exists consecutively, or additional code or data need to follow it.
It should also be noted that the DOSSEG option (whether explicitly given to the linker, or passed in an object file) performs different class and segment ordering. If the ORDER directive is used, it overrides the DOSSEG option, causing it to be ignored.
The OSDOMAIN option is used when the application is to run in the operating system domain (ring 0).
The format of the OSDOMAIN option ( short form OSD ) is as follows.
OPTION OSDOMAIN
The OSNAME option can be used to set the name of the target operating system of the executable file generated by the linker. The format of the OSNAME option ( short form OSN ) is as follows.
OPTION OSNAME='string'
The information specified by the OSNAME option will be displayed in the creating a ? executable message. This is the last line of output produced by the linker, provided the QUIET option is not specified. Consider the following example.
option osname='SuperOS'
The last line of output produced by the linker will be as follows.
creating a SuperOS executable
Some executable formats have a stub executable file that is run under 16-bit DOS. The message displayed by the default stub executable file will be modified when the OSNAME option is used. The default stub executable displays the following message:
If the OSNAME option used in the previous example was specified, the default stub executable would generate the following message.
this is a SuperOS executable
The OSVERSION option specifies that the linker should apply the given major and minor version numbers to the PE format image header. This specifies the major and minor versions of the operating system required to load this image. If a version number is not specified, then the built-in value of 1.11 is used. The format of the OSVERSION option ( short form OSV ) is:
OPTION OSVERSION = major[.minor]
The OUTPUT directive overrides the normal operating system specific executable format and creates either a raw binary image or an Intel Hex file. The format of the OUTPUT directive ( short form OUT ) is:
OUTPUT RAW|HEX [OFFSET=n][HSHIFT=n][STARTREC]
[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.
For raw binary files, the position in the file is the linear address after the offset is subtracted from it. Any gaps filled with the value specified through OPTION FILLCHAR (default is 0).
For hex files, the linear address (after subtracting the offset) is used to determine the output record generated. Records contain 16 bytes, unless a gap occurs prior to that in which case the record is shorter, and a new record starts after the gap. There are three types of Intel Hex records. The oldest and most widely used is HEX80, which can only deal with 16-bit addresses. For many ROM-based applications, this is enough, especially once an offset has been subtracted. For maximum versatility, all addresses less than 65536 are generated in this form.
The HEX86 standard creates a segmentation that mirrors the CPU segmentation. Type 02 records define the segment, and all subsequent addresses are based on that segment value. For addresses above 64K, This form is used. A program that understands HEX86 should assume the segment value is zero until an 02 record is encountered. This preserves backward compatibility with HEX80, and allows the automatic selection algorithm used in JWlink to work properly.
Type 02 records are assumed to have segment values that, when shifted left four bits, form a linear address. However, this is not suitable for 24-bit segmented addressing schemes. Therefore, JWlink uses the value specified through OPTION HSHIFT to determine the relationship between segments and offsets. This approach can work with any 16:16 segmented architecture regardless of the segment alignment. The default shift value is 12, representing the conventional 8086 architecture. This is not to be confused with the optional "OUTPUT HSHIFT" value discussed below.
Of course, PROM programmers or third-party tools probably were not designed to work with unconventional shift values, hence for cases where code for a 24-bit (or other non-standard) target needs to be programmed into a PROM or processed by a third-party tool, the "OUTPUT HSHIFT" option can be used to override the OPTION HSHIFT value. This would usually be of the form "OUTPUT HSHIFT=12" to restore the industry standard setting. The default for "OUTPUT HSHIFT" is to follow OPTION HSHIFT. When neither is specified, the default OPTION HSHIFT value of 12 applies, providing industry standard compliance.
If the address exceeds the range of type 02 records (1 MB for HSHIFT=12 and 16 MB for HSHIFT=8), type 04 extended linear records are generated, again ensuring seamless compatibility and migration to large file sizes.
If "STARTREC" is specified for "OUTPUT HEX", the penultimate record in the file (just before the end record) will be a start address record. The value of the start address will be determined by the module start record in an object file, typically the result of an "END start" assembler directive. If the start address is less than 65536 (always for 16-bit applications, and where applicable for 32-bit applications), a type 03 record with segment and offset values will be emitted. If the start address is equal to or greater than 65536, then a type 05 linear starting address record will be generated. Note that neither of these cases depends directly on the "HSHIFT" or "OUTPUT HSIFT" settings. If HSHIFT=8, then the segment and offset values for the start symbol will be based on that number and used accordingly, but unlike other address information in a hex file, this is not derived from a linear address and hence not converted based on the HSHIFT value.
The OVERLAY directive allows you to specify the class of segments which are to be overlayed. The format of the OVERLAY directive ( short form OV ) is:
OVERLAY class{,class}
where <class> is the class name of the segments to be overlayed.
The FILE directive is used to specify the object files that belong to the overlay structure. Each object file defines segments that contain code or data. Segments are assigned a class name by the compiler. A class is essentially a collection of segments with common attributes. For example, compilers assign class names to segments so that segments containing code belong to one class(es) and segments containing data belong to another class(es). When an overlay structure is defined, only segments belonging to certain classes are allowed in the overlay structure. By default, JWlink overlays all segments whose class name ends with "CODE". These segments usually contain the executable code for a program.
It is also possible to overlay other classes. This is done using the OVERLAY directive. For example,
overlay code, far_data
places all segments belonging to the classes "CODE" and "FAR_DATA" in the overlay structure. Segments belonging to the class "FAR_DATA" contain only data. The above OVERLAY directive causes code and data to be overlayed. Therefore, for any module that contains segments in both classes, data in segments with class "FAR_DATA" will be in memory only when code in segments with class "CODE" are in memory. This results in a more efficient use of memory. Of course the data must be referenced only by code in the overlay and it must not be modified.
WARNING! Care must be taken when overlaying data. If a routine modifies data in an overlayed data segment, it should not assume it contains that value if it is invoked again. The data may have been overwritten by another overlay.
If you are linking object files generated by a compiler that uses a class name that does not end with "CODE" for segments containing executable code, the "OVERLAY" directive can be used to identify the classes that belong to the overlay structure. Consider the following example.
Example:
overlay code1, code2
Any segment belonging to the class called "CODE1" or "CODE2" is placed in the overlay structure. Segments belonging to a class whose name ends with "CODE" will no longer be placed in the overlay structure.
This option is intended for 16-bit segmented applications. By default, JWlink automatically groups logical code segments into physical segments. The PACKCODE option is used to specify the size of the physical segment. The format of the PACKCODE option ( short form PACKC ) is:
OPTION PACKCODE=n
[0x]d{d}[k|m]
d represents a decimal digit. If 0x is specified, the string of digits represents a hexadecimal number. If k is specified, the value is multiplied by 1024. If m is specified, the value is multiplied by 1024*1024.
n specifies the size of the physical segments into which code segments are packed. The default value of n is 64K for 16-bit applications. Note that this is also the maximum size of a physical segment. To suppress automatic grouping of code segments, specify a value of 0 for n.
Notes:
This option is intended for 16-bit segmented applications. By default, JWlink automatically groups logical far data segments into physical segments. The PACKDATA option is used to specify the size of the physical segment. The format of the PACKDATA option ( short form PACKD ) is:
OPTION PACKDATA=n
[0x]d{d}[k|m]
d represents a decimal digit. If 0x is specified, the string of digits represents a hexadecimal number. If k is specified, the value is multiplied by 1024. If m is specified, the value is multiplied by 1024*1024.
n specifies the size of the physical segments into which far data segments are packed. The default value of n is 64K for 16-bit applications. Note that this is also the maximum size of a physical segment. To suppress automatic grouping of far data segments, specify a value of 0 for n.
Notes:
The PATH directive is used to specify the directories that are to be searched for object files appearing in subsequent FILE directives. When the PATH directive is specified, the current directory will no longer be searched unless it appears in the PATH directive. The format of the PATH directive ( short form P ) is as follows.
PATH path_name{;path_name}
where <path_name> is a path name.
Consider a directive file containing the following linker directives.
path \math file sin path \stats file mean, variance
It instructs JWlink to process the following object files:
\math\sin.obj \stats\mean.obj \stats\variance.obj
It is also possible to specify a list of paths in a PATH directive. Consider the following example.
path \math;\stats file sin
First, the linker will attempt to load the file "\math\sin.obj". If unsuccessful, the linker will attempt to load the file "\stats\sin.obj".
It is possible to override the path specified in a PATH directive by preceding the object file name in a FILE directive with an absolute path specification. On 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.
path \math file sin path \stats file mean, \mydir\variance
The above directive file instructs the linker to process the following object files:
\math\sin.obj \stats\mean.obj \mydir\variance.obj
The PRIVILEGE option specifies the privilege level (0, 1, 2 or 3) at which the application will run. The format of the PRIVILEGE option ( short form PRIV ) is as follows.
OPTION PRIVILEGE=n
[0x]d{d}[k|m]
d represents a decimal digit. If 0x is specified, the string of digits represents a hexadecimal number. If k is specified, the value is multiplied by 1024. If m is specified, the value is multiplied by 1024*1024.
The default privilege level is 0.
The PROTMODE option specifies that the application will only run in protected mode. This option applies to 16-bit OS/2 or Windows applications only. The format of the PROTMODE option ( short form PROT ) is:
OPTION PROTMODE
The PSEUDOPREEMPTION option specifies that an additional set of system calls will yield control to other processes. Multitasking in current NetWare operating systems is non-preemptive. That is, a process must give up control in order for other processes to execute. Using the PSEUDOPREEMPTION option increases the probability that all processes are given an equal amount of CPU time.
The format of the PSEUDOPREEMPTION option ( short form PS ) is:
OPTION PSEUDOPREEMPTION
The QUIET option tells JWlink to suppress all informational messages. Only warning, error and fatal messages will be issued. By default, JWlink issues informational messages. The format of the QUIET option ( short form Q ) is:
OPTION QUIET
The REDEFSOK option tells JWlink to accept redefined symbols and to generate an executable file anyway. A warning message is displayed if a redefined symbol is detected.
The format of this option ( short form RED ) is:
OPTION REDEFSOK
The NOREDEFSOK option tells JWlink to reject redefined symbols (this is the default setting). An error message is displayed if a redefined symbol is detected, and the executable file is not generated.
The format of the NOREDEFSOK option ( short form NORED ) is:
OPTION NOREDEFSOK
The REENTRANT option specifies that the module is reentrant. That is, if an NLM is LOADed twice, the actual code in the server's memory is reused. The NLM's start procedure is called once for each LOAD. The format of the REENTRANT option ( short form RE ) is as follows.
OPTION REENTRANT
The REFERENCE directive is used to explicitly reference a symbol that is not referenced by any object file processed by the linker. If any symbol appearing in a REFERENCE directive is not resolved by the linker, an error message will be issued for that symbol specifying that the symbol is undefined.
The REFERENCE directive can be used to force object files from libraries to be linked with the application. Also note that a symbol appearing in a REFERENCE directive will not be eliminated by dead code elimination. For more information on dead code elimination, see the section entitled The ELIMINATE Option.
The format of the REFERENCE directive ( short form REF ) is as follows.
REFERENCE symbol_name{, symbol_name}
Consider the following example.
reference domino
The symbol domino will be searched for. The object module that defines this symbol will be linked with the application. Note that the linker will also attempt to resolve symbols referenced by this module.
The RESOURCE directive is used to specify resource files to add to the executable file being generated. The format of the RESOURCE directive ( short form RES ) is as follows.
RESOURCE resource_file{,resource_file}
where <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.
For 16-bit OS/2, Win16 or Win32/Win64 executable files, the RESOURCE option requests the linker to add the specified resource file to the executable file being generated.
For QNX executable files, the RESOURCE option specifies the contents of the resource record.
The RESOURCE option requests the linker to add the specified resource file to the executable file that is being generated. The format of the RESOURCE option ( short form RES ) is:
OPTION RESOURCE[=resource_file]
The RESOURCE option cannot be used for 32-bit OS/2 executables.
The RESOURCE option specifies the contents of the resource record in QNX executable files. The format of the RESOURCE option ( short form RES ) is:
OPTION RESOURCE resource_info
resource_info ::= 'string' | =resource_file
If a resource file is specified, the contents of the resource file are included in the resource record.
The resource record contains, for example, help information and is displayed when the following command is executed.
use <executable>
QNX also provides the usemsg utility to manipulate the resource record of an executable file. Its use is recommended. This utility is described in the QNX "Utilities Reference" manual.
The RUNTIME directive specifies the environment under which the application will run. The format of the RUNTIME directive ( short form RU ) is:
RUNTIME env[=major[.minor]]
env ::= NATIVE | WINDOWS | CONSOLE | POSIX | OS2 | DOSSTYLE
runtime windows=4.0
RUNTIME run_option{,run_option} run_option ::= MINREAL=n | MAXREAL=n | CALLBUFS=n | MINIBuf=n | MAXIBUF=n | NISTACK=n | ISTKSIZE=n | REALBREAK=offset | PRIVILEGED | UNPRIVILEGED offset ::= n | symbol_name
[0x]d{d}[k|m]
d represents a decimal digit. If 0x is specified, the string of digits represents a hexadecimal number. If k is specified, the value is multiplied by 1024. If m is specified, the value is multiplied by 1024*1024.
The default buffer size is zero unless changed using the "CALLBUFS" option. JWlink 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.
RUNTIME ABIVER[=abinum.abiversion] | abispec
abispec ::= abiname[=abiversion]
abiname ::= SVR4 | LINUX | FREEBSD | NETBSD | SOLARIS
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
The RWRELOCCHECK option causes the linker to check for segment relocations to a read/write data segment and issue a warning if any are found. This option is useful if you are building a 16-bit Windows application that may have more than one instance running at a given time.
The format of the RWRELOCCHECK option ( short form RWR ) is:
OPTION RWRELOCCHECK
The "SCREENNAME" option specifies the name of the first screen (the screen that is automatically created when an NLM is loaded). The format of the "SCREENNAME" option (short form "SCR") is as follows.
OPTION SCREENNAME 'name'
If the "SCREENNAME" option is not specified, the description text specified in the "FORMAT" directive is used as the screen name.
The SECTION directive is used to define the start of an overlay. All object files in subsequent FILE directives, up to the next SECTION or END directive, belong to that overlay. The format of the SECTION directive ( short form S ) is:
SECTION [INTO ovl_file]
Placing overlays in separate files has a number of advantages. For example, if your application was linked into one file, it may not fit on a single diskette, making distribution of your application difficult.
The SEGMENT directive is used to set attributes of code and data segments. The format of the SEGMENT directive ( short form SEG ) is:
SEGMENT seg_desc{,seg_desc} seg_desc ::= seg_id {seg_attrs} seg_id ::= 'seg_name' | CLASS 'class_name' | TYPE [CODE | DATA] OS/2: seg_attrs ::= PRELOAD | LOADONCALL | IOPL | NOIOPL | EXECUTEONLY | EXECUTEREAD | READONLY | READWRITE | SHARED | NONSHARED | CONFORMING | NONCONFORMING | PERMANENT | NONPERMANENT | INVALID | RESIDENT | CONTIGUOUS | DYNAMIC Win32/Win64: seg_attrs ::= PAGEABLE | NONPAGEABLE | SHARED | NONSHARED | EXECUTABLE | WRITABLE | READONLY Win16: seg_attrs ::= PRELOAD | LOADONCALL | EXECUTEONLY | EXECUTEREAD | READONLY | READWRITE | SHARED | NONSHARED | MOVEABLE | FIXED | DISCARDABLE VxD: seg_attrs ::= PRELOAD | LOADONCALL | IOPL | NOIOPL | SHARED | NONSHARED | DISCARDABLE | NONDISCARDABLE | CONFORMING | NONCONFORMING | RESIDENT QNX: seg_attrs ::= EXECUTEONLY | EXECUTEREAD | READONLY | READWRITE
The SHARELIB option specifies the file name of an NLM to be loaded as a shared NLM. Shared NLMs contain global code and global data that are mapped into all memory protection domains. This method of loading APIs can be used to avoid ring transitions to call other APIs in other domains.
The format of the SHARELIB option ( short form SHA ) is:
OPTION SHARELIB=shared_nlm
The SHOWDEAD option instructs the linker to list, in the map file ( see the MAP option ), the symbols associated with dead code and unused C++ virtual functions that it has eliminated from the link. The format of the SHOWDEAD option (short form SHO ) is:
OPTION SHOWDEAD
The SHOWDEAD option works best in concert with the ELIMINATE and VFREMOVAL options.
The SMALL option tells JWlink to use the standard overlay manager (as opposed to the dynamic overlay manager) and that near calls can be generated to overlay vectors corresponding to routines defined in the overlayed portion of your program. The format of the SMALL option ( short form SM ) is:
OPTION SMALL
This option should only be specified in the following circumstances.
If the SMALL option is not specified and you are creating an overlayed application, the linker will generate far calls to overlay vectors. In this case, your application must have been compiled using a big code memory model.
The SORT directive is used to sort the symbols in the "Memory Map" section of the map file ( see the MAP option ). By default, symbols are listed on a per module basis in the order the modules were encountered by the linker. That is, a module header is displayed followed by the symbols defined by the module.
The format of the SORT directive ( short form SO ) is:
SORT [GLOBAL] [ALPHABETICAL]
If the SORT directive is specified without any options, as in the following example, the module headers will be displayed each followed by the list of symbols it defines sorted by address.
sort
If only the "GLOBAL" sort option (short form "GL") is specified, as in the following example, the module headers will not be displayed and all symbols will be sorted by address.
sort global
If only the "ALPHABETICAL" sort option (short form "ALP") is specified, as in the following example, the module headers will be displayed each followed by the list of symbols it defines sorted alphabetically.
sort alphabetical
If both the "GLOBAL" and "ALPHABETICAL" sort options are specified, as in the following example, the module headers will not be displayed and all symbols will be sorted alphabetically.
sort global alphabetical
If you are linking a Open Watcom C++ application, mangled names are sorted by using the base name. The base name is the name of the symbol as it appeared in the source file. See the section entitled The MANGLEDNAMES Option for more information on mangled names.
The STACK option can be used to increase the size of the stack. The format of this option ( short form ST ) is:
OPTION STACK=n
where <n> is a numeric value. The complete form of <n> is:
[0x]d{d}[k|m]
d represents a decimal digit. If 0x is specified, the string of digits represents a hexadecimal number. If k is specified, the value is multiplied by 1024. If m is specified, the value is multiplied by 1024*1024.
The default stack size varies for both 16-bit and 32-bit applications depending on the executable format. You can determine the default stack size by looking at the map file that can be generated when an application is linked ( OPTION MAP ).
Note that for ELF binaries the value of the STACK option is ignored, because the size of the stack is not intended to be stored in the binary.
During execution of your program, you may get an error message indicating your stack has overflowed. If you encounter such an error, you must link your application again, this time specifying a larger stack size using the STACK option.
Example:
option stack=8192
For Win32/Win64, see the COMMIT directive for information on how to specify the committed size of the stack.
The STANDARD option instructs JWlink to use the standard overlay manager (as opposed to the dynamic overlay manager). Your application must be compiled for a big code memory model. The format of the STANDARD option ( short form STAN ) is:
OPTION STANDARD
The standard overlay manager is the default. For more information on overlays, see the section entitled DOS: Using Overlays.
The format of the START option is as follows.
OPTION START=symbol_name
For the Netware executable format, the default name of the start procedure is "_Prelude".
The STARTLINK directive is used to indicate the start of a new set of linker commands that are to be processed after the current set of commands has been processed. The format of the STARTLINK directive ( short form STARTL ) is:
STARTLINK
The ENDLINK directive is used to indicate the end of the set of commands identified by the STARTLINK directive.
Static symbols are symbols that cannot be used to resolve externals. They may be contained in a module's symbol table for various reasons. By default, these static symbols do not appear in the map file ( see the MAP option ). If you want static symbols to be displayed in the map file, use the STATICS option.
The format of the STATICS option ( short form STAT ) is:
OPTION STATICS
The STUB option specifies an executable file containing a stub program that is to be placed at the beginning of the executable file being generated. The stub program will be executed if the module is executed under DOS. The format of the STUB option is:
OPTION STUB=stub_name
JWlink will search all paths specified in the PATH environment variable for the stub executable file. The stub executable file specified by the STUB option must not be the same as the executable file being generated.
The SYMFILE option provides a method for specifying an alternate file for debugging information. The format of the SYMFILE option ( short form SYMF ) is:
OPTION SYMFILE[=symbol_file]
By default, no symbol file is generated; debugging information is appended at the end of the executable file. Specifying this option causes JWlink to generate a symbol file. The symbol file contains the debugging information generated by the linker when the DEBUG directive is used. The symbol file can then be used by Open Watcom Debugger. If no debugging information is requested, no symbol file is created, regardless of the presence of the SYMFILE option.
If no file name is specified, the symbol file will have a default file extension of "sym" and the same path and file name as the executable file. Note that the symbol file will be placed in the same directory as the executable file.
Alternatively, a file name can be specified. The following directive instructs the linker to generate a symbol file and call it "myprog.sym" regardless of the name of the executable file.
option symf=myprog
You can also specify a path and/or file extension when using the "SYMFILE=" form of the SYMFILE option.
Notes:
The SYMTRACE directive instructs JWlink to print a list of all modules that reference the specified symbols. The format of this directive ( short form SYMT ) is
SYMTRACE symbol_name{,symbol_name}
where <symbol_name> is the name of a symbol.
The information is displayed in the map file ( see the MAP option ).
Example:
jwlink system my_os op map file test lib math symt sin, cos
JWlink will list, in the map file, all modules that reference the symbols "sin" and "cos".
Also see the MODTRACE directive.
The SYNCHRONIZE option forces an NLM to complete loading before starting to load other NLMs. Normally, the other NLMs are loading during the startup procedure. The format of the SYNCHRONIZE option ( short form SY ) is:
OPTION SYNCHRONIZE
The SYSTEM directive implements a simple macro/script mechanism. You can define, use and delete such macros, and these options are reflected by the three forms of the SYSTEM directive.
The first form of the SYSTEM directive ( short form SYS ) is called a system definition directive. It allows you to associate a set of linker directives with a specified name called the system name. This set of linker directives is called a system definition block. The syntax of a system definition directive is:
SYSTEM BEGIN system_name {directive} END
where <system_name> is a unique system name and <directive> is one or more linker directives. Note that a system definition directive cannot be specified within another system definition directive.
The second form of the SYSTEM directive is called a system deletion directive. It allows you to remove the association of a set of linker directives with a system name. The syntax of a system deletion directive is:
SYSTEM DELETE system_name
where <system_name> is a defined system name.
The third form of the SYSTEM directive is:
SYSTEM system_name
where <system_name> is a defined system name. When this form of the SYSTEM directive is encountered, all directives specified in the system definition block identified by <system_name> will be processed.
Let us consider an example that demonstrates the use of the SYSTEM directive. The following linker directives define a system called statistics.
system begin statistics
format dos
libpath \libs
library stats, graphics
option stack=8k
end
They specify that a statistics application is to be created by using the libraries "stats.lib" and "graphics.lib". These library files are located in the directory "\libs". The application requires a stack size of 8k and the specified format of executable will be generated.
Suppose the linker directives in the above example are contained in the file "stats.lnk". If we wish to create a statistics application, we can issue the following command.
jwlink @stats system statistics file myappl
As demonstrated by the above example, the SYSTEM directive can be used to localize the common attributes that describe a class of applications.
The system deletion directive can be used to redefine a previously defined system. Consider the following example:
system begin at_dos
libpath %WATCOM%\lib286
libpath %WATCOM%\lib286\dos
format dos ^
end
system begin n98_dos
sys at_dos ^
libpath %WATCOM%\lib286\dos\n98
end
system begin dos
sys at_dos ^
end
If you wish to redefine the definition of the "dos" system, you can specify the following set of directives:
system delete dos
system begin dos
sys n98_dos ^
end
This effectively redefines a "dos" system to be equivalent to a "n98_dos" system (NEC PC-9800 DOS), rather than the previously defined "at_dos" system (AT-compatible DOS).
For additional examples on the use of the SYSTEM directive, examine the contents of the jwlink.lnk file. The file jwlink.lnk is a special linker directive file that is automatically processed by JWlink before processing any other directives.
The default name of the linker directive file (jwlink.lnk) can be overridden by the JWLINK_LNK environment variable. If the specified file can't be opened, the default file name will be used. For example, if the JWLINK_LNK environment variable is defined as follows
set JWLINK_LNK=my.lnk
then JWlink will attempt to use a my.lnk directive file, and if that file cannot be opened, the linker will revert to using the default jwlink.lnk file.
There are two special system names. When the linker has processed all object files and the executable file format has not been determined, and a system definition block has not been processed, the directives specified in the "286" or "386" system definition block will be processed. The "386" system definition block will be processed if a 32-bit object file has been processed. Furthermore, only a restricted set of linker directives is allowed in a "286" and "386" system definition block. They are as follows.
The THREADNAME option is used to specify the pattern to be used for generating thread names. The format of the THREADNAME option ( short form THR ) is as follows.
OPTION THREADNAME 'thread_name'
The first thread name is generated by appending "0" to thread_name, the second by appending "1" to thread_name, etc. If the THREADNAME option is not specified, the first 5 characters of the description specified in the FORMAT directive are used as the pattern for generating thread names.
The TOGGLERELOCS option is used with LX format executables under 32-bit DOS/4G only. The INTERNALRELOCS option causes JWlink to include internal relocation information in DOS/4G LX format executables. Having done so, the linker normally clears the "internal fixups done" flag in the LX executable header (bit 0x10). The TOGGLERELOCS option causes the linker to toggle the value of the "internal fixups done" flag in the LX executable header (bit 0x10). This option is used with DOS/4G non-zero based executables. Contact Tenberry Software for further explanation.
The format of the TOGGLERELOCS option ( short form TOG ) is:
OPTION TOGGLERELOCS
The UNDEFSOK option tells JWlink to generate an executable file even if undefined symbols are present. By default, no executable file will be generated if undefined symbols are present.
The format of the UNDEFSOK option ( short form U ) is:
OPTION UNDEFSOK
The NOUNDEFSOK option tells JWlink to not generate an executable file if undefined symbols are present. This is the default behaviour.
The format of the NOUNDEFSOK option ( short form NOU ) is:
OPTION NOUNDEFSOK
The VECTOR directive forces JWlink to generate an overlay vector for the specified symbols and is intended to be used when the NOINDIRECT option is specified.
The format of the VECTOR directive ( short form VE ) is as follows.
VECTOR symbol_name{,symbol_name}
For more information on overlays, see the section entitled DOS: Using Overlays.
The VERBOSE option controls the amount of information produced by JWlink in the map file. The format of the VERBOSE option ( short form V ) is:
OPTION VERBOSE
If the VERBOSE option is specified, the linker will list, for each object file, all segments it defines and their sizes. By default, this information is not produced in the map file.
The VERSION option can be used to identify the application so that it can be distinguished from other versions (releases) of the same application.
This option is most useful when creating a DLL or NLM since applications that use the DLL or NLM may only execute with a specific version of the DLL or NLM.
The format of the VERSION option ( short form VERS ) is:
OS/2, Win16, Win32/Win64:
OPTION VERSION=major[.minor]
Netware:
OPTION VERSION=major[.minor[.revision]]
The VFREMOVAL option is an Open Watcom peculiarity - it probably has no effect at all for modules generated by other compilers. This option instructs the linker to remove unused C++ virtual functions. The format of the VFREMOVAL option ( short form VFR ) is as follows.
OPTION VFREMOVAL
If the VFREMOVAL option is specified, the linker will attempt to eliminate unused virtual functions. In order for the linker to do this, the Open Watcom C++ "zv" compiler option must be used for all object files in the executable. The VFREMOVAL option works best in concert with the ELIMINATE option.
The XDCDATA option specifies the name of a file that contains Remote Procedure Call (RPC) descriptions for calls in this NLM. RPC descriptions for APIs make it possible for APIs to be exported across memory-protection domain boundaries.
The format of the XDCDATA option ( short form XDC ) is as follows.
OPTION XDCDATA=rpc_file
Input to JWlink is specified on the command line and can be redirected to one or more files or environment strings. JWlink command line format is as follows.
JWLINK {directive}
where directive is any of the following:
You can view all the directives specific to DOS executable files by simply typing the following:
jwlink ? dos
JWlink uses all available memory when linking an application. It is possible for the size of the image being linked to exceed the amount of memory available in your machine, particularly if the image file is to contain debugging information. For this reason, a temporary disk file is used when all available memory is used by JWlink.
Normally, the temporary file is created in the current working directory. However, by defining the "tmp" environment variable to be a directory, you can tell JWlink where to create the temporary file. This can be particularly useful if you have a RAM disk. Consider the following definition of the "tmp" environment variable.
set tmp=\tmp
JWlink will create the temporary file in the directory "\tmp".
Overlays are used primarily for large programs where memory requirements do not permit all portions of the program to reside in memory at the same time. An overlayed program consists of a root and a number of overlay areas.
The root always resides in memory. The root usually contains routines that are frequently used. For example, a floating-point library might be placed in the root. Also, any modules extracted from a library file during the linking process are placed in the root unless the DISTRIBUTE option is specified. This option tells JWlink to distribute modules extracted from libraries throughout the overlay structure. Libraries can also be placed in the overlay structure by using the FIXEDLIB directive.
An overlay area is a piece of memory shared by various parts of a program. Each overlay area has a structure associated with it. This structure defines where in the overlay area sections of a program are loaded. Sections of a program that are loaded into an overlay area are called overlays.
JWlink supports two overlay managers: the standard overlay manager and the dynamic overlay manager. The standard overlay manager requires the user to create an overlay structure that defines the "call" relationship between the object modules that comprise an application. It is the responsibility of the user to define an optimal overlay structure so as to minimize the number of calls that cause overlays to be loaded. The SMALL and STANDARD options select the standard overlay manager. The SMALL option is required if you are linking an application compiled for a small code memory model. The STANDARD option is required if you are linking an application compiled for a big code memory model. By default, JWlink assumes your application has been compiled using a memory model with a big code model. Option STANDARD is the default.
The DYNAMIC option selects the dynamic overlay manager. The dynamic overlay manager is more sophisticated than the standard overlay manager. The user need not be concerned about the "call" relationship between the object modules that comprise an application. Basically, each module is placed in its own overlay. The dynamic overlay manager swaps each module (overlay) into a single overlay area. This overlay area is used as a pool of memory from which memory for overlays is allocated. The larger the memory pool, the greater the number of modules that can simultaneously reside in memory. The size of the overlay area can be controlled by the AREA option.
Note that the dynamic overlay manager can only be used with applications that have been compiled using the "of" option and a big code memory model.
Consider the following directive file.
# # Define files that belong in the root. # file file0, file1 # # Define an overlay area. # begin section file file2 section file file3, file4 section file file5 end
The following diagram depicts the overlay structure.
+-----------------------------------+ <- start of root | | | file0 | | file1 | | | +-----------+-----------+-----------+ <- start of overlay | #1 | #2 | #3 | area | | | | | file2 | file3 | file5 | | | file4 | | | | | | +-----------+-----------+-----------+
Notes:
In the previous example, only one overlay area was defined. It is possible to define more than one overlay area as demonstrated by the following example.
# # Define files that belong in the root. # file file0, file1 # # Define an overlay area. # begin section file file2 section file file3, file4 section file file5 end # # Define an overlay area. # begin section file file6 section file file7 section file file8 end
Two overlay areas are defined. The first is identical to the overlay area defined in the previous example. The second overlay area contains three overlays; the first overlay (overlay #4) contains file6, the second overlay (overlay #5) contains file7, and the third overlay (overlay #6) contains file8.
The following diagram depicts the overlay structure.
+-----------------------------------+ <- start of root | | | file0 | | file1 | | | +-----------+-----------+-----------+ <- start of overlay | #1 | #2 | #3 | area | | | | | file2 | file3 | file5 | | | file4 | | | | | | +-----------+-----------+-----------+ <- start of overlay | #4 | #5 | #6 | area | | | | | file6 | file7 | file8 | | | | | +-----------+-----------+-----------+
In the above example, the AUTOSECTION directive could have been used to define the overlays for the second overlay area. The following example illustrates the use of the AUTOSECTION directive.
# # Define files that belong in the root. # file file0, file1 # # Define an overlay area. # begin section file file2 section file file3, file4 section file file5 end # # Define an overlay area. # begin autosection file file6 file file7 file file8 end
In all of the above examples the overlays are placed in the executable file. It is possible to place overlays in separate files by specifying the INTO option in the SECTION directive that starts the definition of an overlay. By specifying the INTO option in the AUTOSECTION directive, all overlays created as a result of the AUTOSECTION directive are placed in one overlay file.
Consider the following example. It is similar to the previous example except for the following. Overlay #1 is placed in the file "ovl1.ovl", overlay #2 is placed in the file "ovl2.ovl", overlay #3 is placed in the file "ovl3.ovl" and overlays #4, #5 and #6 are placed in file "ovl4.ovl".
# # Define files that belong in the root. # file file0, file1 # # Define an overlay area. # begin section into ovl1 file file2 section into ovl2 file file3, file4 section into ovl3 file file5 end # # Define an overlay area. # begin autosection into ovl4 file file6 file file7 file file8 end
Let us again consider the above example but this time we will use the dynamic overlay manager. The easiest way to take the above overlay structure and use it with the dynamic overlay manager is to simply specify the DYNAMIC option.
option DYNAMIC
Even though we have defined an overlay structure with more than one overlay area, JWlink will allocate one overlay area and overlays from both overlay areas will be loaded into a single overlay area. The size of the overlay area created by JWlink will be twice the size of the largest overlay area (unless the AREA option is used).
To take full advantage of the dynamic overlay manager, the following sequence of directives should be used.
# # Define files that belong in the root. # file file0, file1 # # Define an overlay area. # begin autosection into ovl1 file file2 autosection into ovl2 file file3 file file4 autosection into ovl3 file file5 autosection into ovl4 file file6 file file7 file file8 end
In the above example, each module will be in its own overlay. This will result in a module being loaded into memory only when it is required. If separate overlay files are not required, a single AUTOSECTION directive could be used as demonstrated by the following example.
# # Define files that belong in the root. # file file0, file1 # # Define an overlay area. # begin autosection file file2 file file3 file file4 file file5 file file6 file file7 file file8 end
Nested overlay structures occur when the BEGIN-END directives are nested and are only useful if the standard overlay manager is being used. If you have selected the dynamic overlay manager, the nesting levels will be ignored and each overlay will be loaded into a single overlay area.
Consider the following directive file.
# # Define files that belong in the root. # file file0, file1 # # Define a nested overlay structure. # begin section file file2 section file file3 begin section file file4, file5 section file file6 end end
Notes:
The following diagram depicts the overlay structure.
+-----------------------------------+ <- start of root | | | file0 | | file1 | | | +-----------+-----------------------+ <- start of overlay | #1 | #2 | area | | | | file2 | file3 | | | | | | | | +-----------+-----------+ <- start of overlay | | #3 | #4 | area | | | | | | file4 | file6 | | | file5 | | | | | | +-----------+-----------+-----------+
Notes:
Nested overlays are particularly useful when the routines that make up one overlay are used only by a few other overlays. In the above example, the routines in overlay #2 would only be used by routines in overlay #3 and overlay #4 but not by overlay #1.
JWlink handles all the details of loading overlays. No changes to a program have to be made if, for example, it becomes so large that you have to change to an overlay structure. Certain rules have to be followed to ensure the proper execution of your program. These rules pertain more to the organization of the components of your program and less to the way it was coded.
+-----------------------+ <- 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.
void far _ovl_addarea(unsigned segment,unsigned size);
The first argument is the segment address of the block memory you wish to add. The second argument is the size, in paragraphs, of the memory block.
In assembly language, the function is called _ovl_addarea_ with the first argument being passed in register AX and the second argument in register DX.
The overlay manager normally opens overlay files, including executable files containing overlays, in compatibility mode. Compatibility mode is a sharing mode. A file opened in compatibility mode means that it can be opened any number of times provided that it is not currently opened under one of the other sharing modes. In other words, the file must always be opened in compatibility mode.
The overlay manager keeps most recently used overlay files open for efficiency. This means that any application, including the currently executing application, that may want to open an overlay file, must open it in compatibility mode. For example, the executing application may have data at the end of the executable file that it wishes to access.
If an application wishes to open the file in a sharing mode other than compatibility mode, the function _ovl_openflags has been defined which allows the caller to specify the sharing mode with which the overlay files will be opened by the overlay manager. This function is defined as follows.
unsigned far _ovl_openflags(unsigned sharing_mode);
Legal values for the sharing mode are as follows.
Sharing Mode Value -------------------- ----- compatibility mode 0x00 deny read/write mode 0x01 deny write mode 0x02 deny read mode 0x03 deny none mode 0x04
The return value is the previous sharing mode used by the overlay manager to open overlay files.
Note that DOS opens executable files in compatibility mode when loading them for execution. This is important for executable files on networks that may be accessed simultaneously by many users.
In assembly language, the function is called _ovl_openflags_ with its argument being passed in register AX.
This chapter deals specifically with aspects of RAW executable files.
Input to JWlink is specified on the command line and can be redirected to one or more files or environment strings. JWlink command line format is as follows.
JWLINK {directive}
where directive is any of the following:
You can view all the directives specific to RAW executable files by simply typing the following:
jwlink ? raw
JWlink uses all available memory when linking an application. It is possible for the size of the image being linked to exceed the amount of memory available in your machine, particularly if the image file is to contain debugging information. For this reason, a temporary disk file is used when all available memory is used by JWlink.
Normally, the temporary file is created in the current working directory. However, by defining the "tmp" environment variable to be a directory, you can tell JWlink where to create the temporary file. This can be particularly useful if you have a RAM disk. Consider the following definition of the "tmp" environment variable.
set tmp=\tmp
JWlink will create the temporary file in the directory "\tmp".
This chapter deals specifically with aspects of ELF executable files. The ELF executable file format will only run under the operating systems that support the ELF executable file format.
Input to JWlink is specified on the command line and can be redirected to one or more files or environment strings. JWlink command line format is as follows.
JWLINK {directive}
where directive is any of the following:
You can view all the directives specific to ELF executable files by simply typing the following:
jwlink ? elf
This chapter deals specifically with aspects of NetWare executable files. The Novell NetWare executable file format will only run under NetWare operating systems.
Input to JWlink is specified on the command line and can be redirected to one or more files or environment strings. JWlink command line format is as follows.
JWLINK {directive}
where directive is any of the following:
You can view all the directives specific to NetWare executable files by simply typing the following:
jwlink ? nov
There are multiple types of NLMs, each identified by the file extension of the executable file and the internal module type number.
|
JWlink can generate all types of NLMs by utilising the numerical value of the module type.
This chapter deals specifically with aspects of OS/2 executable files. The OS/2 16-bit executable file format will run under the following operating systems.
The OS/2 32-bit linear executable file format will run under the following operating systems.
Input to JWlink is specified on the command line and can be redirected to one or more files or environment strings. JWlink command line format is as follows.
JWLINK {directive}
where directive is any of the following:
You can view all the directives specific to OS/2 executable files by simply typing the following:
jwlink ? os2
Program modules are contained in files whose name has a file extension of "exe". Dynamic Link Libraries are contained in files whose name has a file extension of "dll". JWlink "FORMAT" directive can be used to select the type of executable file to be generated.
Let us consider some of the advantages of using Dynamic Link Libraries over standard libraries.
system os2v2_dll
In addition, you must specify which functions in the Dynamic Link Library are to be made available to applications which use it. This is achieved by using the EXPORT directive for each function that can be called by an application.
Dynamic Link Libraries can reference other Dynamic Link Libraries. References to other Dynamic Link Libraries are resolved by specifying IMPORT directives or using import libraries.
To use a Dynamic Link Library, you must tell JWlink which functions are contained in a Dynamic Link Library and the name of the Dynamic Link Library. This is achieved in two ways.
The first method is to use the IMPORT directive. This directive names the function and the Dynamic Link Library it belongs to so that JWlink can generate an import definition in the program module.
The second method is to use import libraries. An import library is a standard library which contains object modules with special object records that define the functions belonging to a Dynamic Link Library. An import library is created from a Dynamic Link Library using a Library Manager ([J]WLIB, LIB, ...). The resulting import library can then be specified in a LIBRARY directive in the same way one would specify a standard library.
Using an import library is the preferred method of providing references to functions in Dynamic Link Libraries. When a Dynamic Link Library is modified, typically the import library corresponding to the modified Dynamic Link Library is updated to reflect the changes. Hence, any directive file that specifies the import library in a LIBRARY directive need not be modified. However, if you are using IMPORT directives, you may have to modify the directives to reflect the changes in the Dynamic Link Library.
This chapter deals specifically with aspects of Phar Lap 386|DOS-Extender executable files. The Phar Lap executable file format will run under the following operating systems.
Input to JWlink is specified on the command line and can be redirected to one or more files or environment strings. JWlink command line format is as follows.
JWLINK {directive}
where directive is any of the following:
You can view all the directives specific to Phar Lap 386|DOS-Extender executable files by simply typing the following:
jwlink ? phar
Essentially, what 386|DOS-Extender does is provide an interface between your application and DOS running in real mode. Whenever your program issues a software interrupt (DOS and BIOS system calls), 386|DOS-Extender intercepts the requests, transfers data between the protected-mode and real-mode address space, and calls the corresponding DOS system function running in real mode.
When running a program under 386|DOS-Extender, memory for the program is allocated from conventional memory (memory below one megabyte) and extended memory. Conventional memory is allocated from a block of memory that is obtained from DOS by 386|DOS-Extender at initialization time. By default, all available memory is allocated at initialization time; no conventional memory remains free. The "MINREAL" and "MAXREAL" options of the "RUNTIME" directive control the amount of conventional memory initially left free by 386|DOS-Extender.
Part of the conventional memory allocated at initialization is required by 386|DOS-Extender. The following is allocated from conventional memory for use by 386|DOS-Extender.
When a program is loaded by 386|DOS-Extender, memory to hold the entire program is allocated. In addition, memory beyond the end of the program is allocated for use by the program. By default, all extra memory is allocated when the program is loaded. It is assumed that any memory not required by the program is freed by the program. The amount of memory allocated at the end of the program is controlled by the "MINDATA" and "MAXDATA" options.
JWlink uses all available memory when linking an application. It is possible for the size of the image being linked to exceed the amount of memory available in your machine, particularly if the image file is to contain debugging information. For this reason, a temporary disk file is used when all available memory is used by JWlink.
Normally, the temporary file is created in the current working directory. However, by defining the "tmp" environment variable to be a directory, you can tell JWlink where to create the temporary file. This can be particularly useful if you have a RAM disk. Consider the following definition of the "tmp" environment variable.
set tmp=\tmp
JWlink will create the temporary file in the directory "\tmp".
This chapter deals specifically with aspects of QNX executable files. The QNX executable file format will only run under the QNX operating system.
Input to JWlink is specified on the command line and can be redirected to one or more files or environment strings. JWlink command line format is as follows.
jwlink {directive}
where directive is any of the following:
You can view all the directives specific to QNX executable files by simply typing the following:
jwlink ? qnx
This chapter deals specifically with aspects of Win16 executable files. The Win16 executable file format will run under Windows 3.x, Windows 9x/ME and Windows NT/2k/XP/Vista/7.
Input to JWlink is specified on the command line and can be redirected to one or more files or environment strings. JWlink command line format is as follows.
JWLINK {directive}
where directive is any of the following:
You can view all the directives specific to Win16 executable files by simply typing the following:
jwlink ? win
This is a memory-management issue for real-mode Windows only. However, if a DLL is marked as "fixed", Windows 3.x will place it in the lower 640K real-mode memory (regardless of the mode in which Windows 3.x is running). Since the lower 640K is a limited resource, you normally would want a DLL to be marked as "moveable".
Most segments, including code and data segments, are moveable. Some exceptions exist. If your program contains a far pointer, the segment which it references must be fixed. If it were moveable, the segment address portion of the far pointer would be invalid when Windows moved the segment.
All non-Windows programs are assigned fixed segments when they run under Windows. These segments must be fixed since there is no information in the executable file that describes how segments are referenced. Whenever possible, your application should consist of moveable segments since fixed segments can cause memory management problems.
For details about available segment attributes, see the SEGMENT directive.
Moveable segments can also be discardable. Memory allocated to a discardable segment can be freed and used for other memory requests. A "least recently used" (LRU) algorithm is used to determine which segment to discard when more memory is required.
Discardable segments are usually segments that do not change once they are loaded into memory. For example, code segments are discardable since programs do not usually modify their code segments. When a segment is discarded, it can be reloaded into memory by accessing the executable file.
Discardable segments must be moveable since they can be reloaded into a different area in memory than the area they previously occupied. Note that moveable segments need not be discardable. Obviously, data segments that contain read/write data cannot be discarded.
JWlink can generate two forms of executable files; program modules and Dynamic Link Libraries. A program module is the executable file that gets loaded by the operating system when you run your application. A Dynamic Link Library is really a library of routines that are called by a program module but not linked into the program module. The executable code in a Dynamic Link Library is loaded by the operating system during the execution of a program module when a routine in the Dynamic Link Library is called.
Program modules are contained in files whose name has a file extension of "exe". Dynamic Link Libraries are contained in files whose name has a file extension of "dll". The FORMAT or SYSTEM directives can be used to select the type of executable file to be generated.
Let us consider some of the advantages of using Dynamic Link Libraries over standard libraries.
system win16_dll
In addition, you must specify which functions in the Dynamic Link Library are to be made available to applications which use it. This is achieved by using the EXPORT directive for each function that can be called by an application.
Dynamic Link Libraries can reference other Dynamic Link Libraries. References to other Dynamic Link Libraries are resolved by specifying IMPORT directives or using import libraries.
To use a Dynamic Link Library, you must tell JWlink which functions are contained in a Dynamic Link Library and the name of the Dynamic Link Library. This is achieved in two ways.
The first method is to use the IMPORT directive. This directive names the function and the Dynamic Link Library it belongs to so that JWlink can generate an import definition in the program module.
The second method is to use import libraries. An import library is a standard library which contains object modules with special object records that define the functions belonging to a Dynamic Link Library. An import library is created from a Dynamic Link Library using a Library Manager ([J]WLIB, LIB, ...). The resulting import library can then be specified in a LIBRARY directive in the same way one would specify a standard library.
Using an import library is the preferred method of providing references to functions in Dynamic Link Libraries. When a Dynamic Link Library is modified, typically the import library corresponding to the modified Dynamic Link Library is updated to reflect the changes. Hence, any directive file that specifies the import library in a LIBRARY directive need not be modified. However, if you are using IMPORT directives, you may have to modify the directives to reflect the changes in the Dynamic Link Library.
This chapter deals specifically with aspects of VxD executable files.
Input to JWlink is specified on the command line and can be redirected to one or more files or environment strings. JWlink command line format is as follows.
JWLINK {directive}
where directive is any of the following:
You can view all the directives specific to WinVxD executable files by simply typing the following:
jwlink ? win vxd
The Win32 executable file format ( aka PE or PE32 format ) is the native format of Windows 9x/ME and Windows NT/2k/XP/Vista/7. It may also run under Windows 3.x using the Win32S subsystem ( you are restricted to a subset of the Win32 API ). Some DOS extenders - HX, WDOSX, Borland's RTM32 and Phar Lap's TNT - are also using the PE32 format.
The Win64 executable file format ( aka PE32+ format ) will only run on 64-bit versions of Windows.
Input to JWlink is specified on the command line and can be redirected to one or more files or environment strings. JWlink command line format is as follows.
JWLINK {directive}
where directive is any of the following:
You can view all the directives specific to Win32 executable files by simply typing the following:
jwlink ? pe
Program modules are contained in files whose name has a file extension of "exe". Dynamic Link Libraries are contained in files whose name has a file extension of "dll". The FORMAT or SYSTEM directives can be used to select the type of executable file to be generated.
Let us consider some of the advantages of using Dynamic Link Libraries over standard libraries.
system pe_dll
In addition, the functions in the dll that are to be called by other modules must be made publicly available. This is achieved by using the EXPORT directive for each such function. To create an import library to be used by applications that want to call the dll's functions, see the IMPLIB Option.
Dynamic Link Libraries can reference other Dynamic Link Libraries. References to other Dynamic Link Libraries are resolved by specifying IMPORT directives or using import libraries.
To use a Dynamic Link Library, you must tell JWlink which functions are contained in a Dynamic Link Library and the name of the Dynamic Link Library. This is achieved in two ways.
The first method is to use the IMPORT directive. This directive names the function and the Dynamic Link Library it belongs to so that JWlink can generate an import definition in the program module.
The second method is to use import libraries. An import library is a standard library which contains object modules with special object records that define the functions belonging to a Dynamic Link Library. An import library is created from a Dynamic Link Library using a Library Manager. Optionally, JWlink may create an import library with the IMPLIB option when linking a DLL . The resulting import library can then be specified in a LIBRARY directive in the same way one would specify a standard library.
Using an import library is the preferred method of providing references to functions in Dynamic Link Libraries. When a Dynamic Link Library is modified, typically the import library corresponding to the modified Dynamic Link Library is updated to reflect the changes. Hence, any directive file that specifies the import library in a LIBRARY directive need not be modified. OTOH, if you are using IMPORT directives, you may have to modify the directives to reflect the changes in the Dynamic Link Library.
|
There's no direct replacement for MS link's /DEF option, which tells the linker to scan a so-called Module Definition File. However, since the main usage of such files is to define exports, it's simple to replace them with standard linker directive files.
Here's an example. Module Definition File MYDLL.DEF:
LIBRARY MYDLL EXPORTS MyFunction1 MyFunction2 MyFunction3
can be replaced by linker directive file MYDLL.RSP:
OP MODNAME=MYDLL OP FUZZYEXPORT EXPORT { MyFunction1 MyFunction2 MyFunction3 }
and that file is added to JWlink's commandline with the @ directive:
jwlink format win pe dll file mydll.obj @MYDLL.RSP
JWlink Diagnostic Messages
JWlink issues three classes of messages; fatal errors, errors and warnings. Each message has a 4-digit
number associated with it. Fatal messages start with the digit 3, error messages start with the digit 2, and warning
messages start with the digit 1. It is possible for a message to be issued as a warning or an error.
If a fatal error occurs, the linker will terminate immediately and no executable file will be generated.
If an error occurs, the linker will continue to execute so that all possible errors are issued. However, no executable file will be generated since these errors do not permit a proper executable file to be generated.
If a warning occurs, the linker will continue to execute. A warning message is usually informational and does not prevent the creation of a proper executable file. However, all warnings should eventually be corrected.
The messages listed contain references to %s, %S, %a, %x, %d, %l, and %f. They represent strings that are substituted by JWlink to make the error message more precise.
The following is a list of all warning and error messages produced by JWlink followed by a description of the message. A message may contain more than one reference to "%s". In such a case, the description will reference them as "%sn" where n is the occurrence of "%s" in the message.
C>copy/b *.obj all.obj
This technique only works for OMF-type object files. This significantly reduces the size of the file list the linker must maintain.
Your application must not attempt to define these symbols. "%s" identifies the reserved symbol.
ALIAS foo1=foo2, foo2=foo1
FORMAT OS2
will generate this message.
JWlink will assume that the directives found in .drectve will follow the syntax understood by MS link. Hence JWlink must translate them to its own format. Currently the following directives are translated:
-entry:start_label
-defaultlib:library_name
-export:exported_name[=internal_name]
Additionally, JWlink will understand and translate:
-import:internal_name=module_name[.external_name | ordinal]
The MS linker has no -import directive and also won't understand anymore an IMPORT section in a module definition file (.DEF) as the 16-bit linker did. Hence this is currently kind of exclusive JWlink feature.