Super Prev Next

Linking your program

Once you have the object modules for your program produced by the compiler, you have to use a linker to link them together with XDS runtime libraries and create an executable (EXE or DLL) file. You may use XDS Linker (XLINK), described in this chapter, or a third-party linker which accepts input object files and libraries in OMF or COFF format.

The compiler may invoke a linker for you seamlessly (see Seamless linking).


Super Prev Next

Starting the linker

In order to link your program you have to invoke the linker specifying its input on the command line:

    xlink [options] [@responsefile] {filename}

Linker input consists of options and file name parameters. Command line options have to start with either "-" or "/" character. Option names are case insensitive; some of them allow shortening. File name parameters are used to specify object, library, and resource files to be linked.

Example:

    xlink /sys=c /name=hello hello.obj d:\xds\lib\x86\libxds.lib


Super Prev Next

Using response files

Instead of specifying all linker input on the command line, you may put some options and file name parameters into a response file. You may combine response files with options and parameters on the command line. Options in a response file have to be separated by any whitespace characters (including line breaks).

When you invoke the linker, use the following syntax:

    xlink {@responsefile}

where responsefile is the name of the response file.

The "@" symbol indicates that the file is a response file. If the file is not in the working directory, specify the path for the file as well as the file name. If the linker cannot find a response file, it stops linking.

You can begin using a response file at any point on the linker command line or in another response file.

Options can appear anywhere in a response file. If an option is not valid, the linker generates an error message and stops linking.

The semi-colon character (";") at the beginning of a line forces the linker to treat it as a comment and ignore the whole line.


Super Prev Next

Sample response file

    ; XLINK response file
    /sys=VIO
    /stack=100000
    /name=runme.exe
    commands.obj
    echo.obj
    genecho.obj
    nodes.obj
    types.obj
    runme.obj
    d:\xds\lib\x86\xstart.lib
    d:\xds\lib\x86\libxds.lib
    d:\xds\lib\x86\os2face.lib


Super Prev Next

Seamless linking

The compiler, when invoked in the PROJECT mode, may automatically produce a response file and invoke the linker. This is the default behaviour after XDS installation.

Have to write something here.more in readme files. !!!


Super Prev Next

Input and output


Super Prev Next

Specifying input files

To specify an input object, library, or resource file, pass its name to xlink as a command line parameter or include its name into a response file. If a specified file name has no extension, .OBJ is assumed, so ensure that you specify library and resource files with extensions.


Super Prev Next

Specifying output format

XLINK supports two output formats - Linear Executable Module Format (LX), used in OS/2, and Portable Executable Format (PE), used in Windows. Default is a format native to the host system. In order to explicitly specify the output format, use the option /IMAGEFORMAT=format, where format can be PE or LX.

The linker may produce executable modules (EXE) and dynamic link libraries (DLL) in both LX and PE formats. An EXE file can be executed directly, for instance, by typing its name at the command prompt. In contrast, a DLL is executed when it is loaded by other processes, and cannot be invoked independently.


Super Prev Next

Producing an executable module

The linker produces executable (EXE) files by default.

To reduce the size of the EXE file and improve its performance, use the following options:

Use the /NAME option to specify an output file name. If you do not specify an extension, the linker will automatically append the extension .EXE to the name you provided. If you omit the /NAME option, the linker will produce an .EXE file named after first .OBJ file specified.

Use the /ENTRY option to explicitly set an entry point for the executable and the /NOENTRY option to set no entry point.


Super Prev Next

Producing a dynamic link library

A dynamic link library (DLL) contains executable code for common functions, just as an ordinary library (.LIB) file does. However, when you link with a DLL (directly or using an import library), the code in the DLL is not copied into the executable (EXE) file. Instead, only the import definitions for DLL functions are copied. At run time, the dynamic link library is loaded into memory, along with the EXE file.

To produce a DLL as output, use the /DLL option. If you are using an export definition file (.EDF), specify its name in that same option as /DLL=edfname. For more information on using .EDF files, see section Using export definition files.

To reduce the size of the DLL and improve its performance, use the following options:

Use the /EXPORT command line option or an export definition file to explicitly specify the functions and data you want to make available to other executables.

Once you have built a DLL, you may produce an executable that links to that DLL. This can be done in two ways:

Using the DLL itself.

If you want to produce a PE executable, you can specify a DLL name on the command line as a file name parameter, but make sure that the specified extension is .DLL.
Using an import library.

Use the XLIB utility to create an import library for one or more DLLs. See Import library creation for more information

If you do not specify an extension for the output file name in the /NAME option, the linker automatically adds the extension .DLL to the name you provide. If you omit the /NAME option and there is no specification in any object or library file, the linker generates a .DLL file named after the first object file specified.

Use the /ENTRY option to explicitly set DLL initialization routine and the /NOENTRY option to avoid setting any initialization routine.


Super Prev Next

Including debug information

Use the /DEBUG option to include symbolic debug information into the output file, to enable debugging at the source level, profiling, and comprehensive call history dump. The linker will embed symbolic data and line number information in the output file. The linker recognizes debug information in two formats - HLL4 and CodeView. Output format is always the one used in input object and library files. If there are input files containing debug information in different formats, a warning message is produced and debug information is not included into the output file.

Note: Linking with /DEBUG increases the size of the output file.


Super Prev Next

Generating a map file

Specify the /MAP option to generate a map file, which lists object modules in your output file and symbol information. If you do not specify a name for the map file, the map file takes the name of the output file with extension .MAP.


Super Prev Next

Linker return codes

The linker has the following return codes:

Code Meaning
0 Linking completed successfully. The linker detected no errors.
255 The linker detected errors during the linking process.


Super Prev Next

Linking with library files


Super Prev Next

Linking with static libraries

The linker uses static library (.LIB) files to resolve external references from the code in the object (.OBJ) files. When the linker finds a function or data reference in an .OBJ file that requires a module from a library, the linker links the module from the library to the output file (for more details see the /SMART option).


Super Prev Next

Linking with dynamic link libraries


Super Prev Next

Using the DLL itself

If you want to produce a PE executable then you can specify a DLL name on the command line as a file name parameter, but make sure that specified extension is .DLL.


Super Prev Next

Using an import library

An import library contains information about procedures and data exported by the DLL. Use the XLIB utility to create an import library, as described in Import library creation.

You may then use the import library with the linker, when you generate executables that reference entities from the DLL. Enter the import library name as a file name parameter on the command line or in a response file.


Super Prev Next

Setting linker options


Super Prev Next

Setting options on the command line

You can specify options anywhere on the command line. Separate options with a space or tab character.

For example, to link an object file with the /MAP option, enter:

    XLINK /MAP myprog.obj


Super Prev Next

Setting numeric arguments

Some linker options take numeric arguments. The linker accepts numeric arguments in special syntax. You can specify numbers in any of the following forms:

Decimal Any number not prefixed with x or 0x is a decimal number.
  For example, 1234 is a decimal number.
Hexadecimal Any number prefixed with x or 0x is a hexadecimal number.
  For example, 0x1234 is a hexadecimal number.
K or M suffixes Any number (either decimal or hexadecimal) is multiplied
  by 1024 if it is ended by suffix K and by 1048576 (1024 * 1024)
  if it is ended by suffix M. For example, 1K is 1024 and
  1M is 1048576.


Super Prev Next

Options reference


Super Prev Next

/ALIGN - Alignment factor

Syntax: /ALIGN=factor
Default: /ALIGN=512

Use the /ALIGN option to set the alignment factor in the output EXE or DLL file.

The alignment factor determines where pages in an executable (EXE or DLL) file start. From the beginning of the file, start of each page is aligned at a multiple (in bytes) of the alignment factor. The alignment factor must be a power of 2, from 1 to 4096.

The default alignment is 512 bytes.


Super Prev Next

/BASE - Load address

Syntax: /BASE=address
Default: /BASE=0x00010000 for LX format
  /BASE=0x00400000 for PE format

Use the /BASE option to specify the preferred load address for the module.


Super Prev Next

/DEBUG - Include debug info

Syntax: /D[EBUG]
Default: do not include debug info

Use the /DEBUG option to include debug information in the output file, enabling it to be debugged at the source level. The linker will embed symbolic data and line number information in the output file.

Note: Linking with /DEBUG increases size of the output file.


Super Prev Next

/DLL - Produce dynamic link library

Syntax: /DLL[=edfname]
Default: build an EXE file

Use the /DLL option to identify the output file as a dynamic link library (.DLL). To use export definition file (.EDF) specify its name after the equals sign: /DLL=edfname. For more information on producing DLLs, see Producing a dynamic link library.

If you do not specify /DLL the linker will produce an EXE file.


Super Prev Next

/ENTRY - Entry point

Syntax: /ENTRY=identifier
Default: use the default entry point

Use the /ENTRY option to explicitly specify an entry point for the EXE module or an initialization routine for the .DLL module. If there is an entry point in any object or library file being linked, it is ignored and a warning message is issued.


Super Prev Next

/NOENTRY - No entry point

Syntax: /NOENTRY
Default: use the default entry point

Use the /NOENTRY option to avoid setting any entry point or initialization routine.


Super Prev Next

/EXPORT - Define exported entities

Syntax: /EXP[ORT]=external[.ordinal][=internal],...
Default: export all

Use the /EXPORT option to specify exported data and functions on the command line.

    xlink . . . /EXPORT=Entry.1=Main_Entry,Main_BEGIN.2


Super Prev Next

/EXTRAALIGNMENT - Align at 16-bytes boundary

Syntax: /EXTRA[ALIGNMENT]
Default: do not align at 16-bytes boundary

Use the /EXTRAALIGNMENT option to align all at a 16-bytes boundary, if necessary.


Super Prev Next

/FIXED - Omit relocation information

Syntax: /FIXED
Default: include relocation information

Use the /FIXED option to force the linker to omit relocation information in the output file.


Super Prev Next

/HEAPCOMMIT - Heap commit size

Syntax: /HEAPCOMMIT=number
Default: /HEAPCOMMIT=0x00001000

Use the /HEAPCOMMIT option to specify the heap commit size of your program.


Super Prev Next

/HEAPSIZE - Heap size

Syntax: /HEAP[SIZE]=number
Default: /HEAPSIZE=0x00002000

Use the /HEAPSIZE option to specify the maximum heap size of your program.


Super Prev Next

/IMAGEFORMAT - Output file format

Syntax: /IMAGE[FORMAT]=format
Default: /IMAGE[FORMAT]=LX under OS/2
  /IMAGE[FORMAT]=PE under Windows

Use the /IMAGEFORMAT option to specify output executable file format. Format can be PE or LX. For more information, see Producing an executable module.


Super Prev Next

/MAP - Produce map file

Syntax: /M[AP][=filename]
Default: do not generate map

Use the /MAP option to generate map file. For more information see Generating a map file.


Super Prev Next

/NAME - Output file name

Syntax: /NAME=filename
Default: use the first linked file name

Use the /NAME option to explicitly specify the output file name. If filename is not specified, the linker will name the output file after the first linked file.


Super Prev Next

/SMART - Enable smart linking

Syntax: /SMART
Default: /SMART

Use the /SMART option to enable smart linking for subsequent files.


Super Prev Next

/NOSMART - Disable smart linking

Syntax: /NOSMART
Default: /SMART

Use the /NOSMART option to disable smart linking for subsequent files.


Super Prev Next

/STACKCOMMIT - Stack commit size

Syntax: /STACKCOMMIT=number
Default: /STACKCOMMIT=0x00002000

Use the /STACKCOMMIT option to specify the stack commit size of your program.


Super Prev Next

/STACKSIZE - Stack size

Syntax: /STACK[SIZE]=number
Default: /STACKSIZE=0x00010000

Use the /STACKSIZE option to specify the maximum stack size of your program.


Super Prev Next

/STUB - Stub file

Syntax: /STUB=filename
Default: no stub file

Use the /STUB option to specify the stub file for your program.


Super Prev Next

/SYS - Application type

Syntax: /SYS=C | W [,number [.number]]
Default: /SYS=C,4.0

Use the /SYS option to force the linker to create console or windows application and specify major and minor OS version.


Super Prev Next

/WARN - Warnings severity level

Syntax: /WARN=(0|1|2|3)
Default: /WARN=2

Use the /WARN option to set the severity level of warnings the linker produces and that causes the warning count to increment. See Linker error and warning messages for the description of error and warning messages.

You can set the severity levels from 0 up to 3.


Super Prev Next

Using export definition files

Export definition files (EDF) are used to specify which procedures and variables are to be visible outside a DLL. EDF also allows arbitrary external names and ordinal numbers to be assigned to those procedures and variables.


Super Prev Next

Export definition file syntax

An .EDF file begins with the LIBRARY section:

     LIBRARY Identifier["." Identifier]

where Identifier is defined as follows:

     identifier = (letter | "_") { letter | digit | "_" | "'")

LIBRARY section is optional and specified library name is unused. After it, the DESCRIPTION section goes:

     DESCRIPTION [ '"' Text '"' ]

DESCRIPTION section is also optional, but if it is present, the specified Text will be written to the output file.

After the DESCRIPTION section, the EXPORTS section goes:

    EXPORTS
        { External [ "=" Internal ] [ "@" Ordinal ] }

The EXPORTS section is used to define the names of procedures and variables exported from the DLL.

External

an external name of an exported object (procedure or variable), i.e. the name which has to be used in other executable modules to reference that object.
Internal

an internal name of that object, i.e. the name under which it appears in an object file. By default, the linker assumes that it is the same as External.
Ordinal

a decimal number specifying ordinal position of the object in the module definition table. If it is not specified, the linker will assign an ordinal number automatically.

The EXPORTS section is optional.


Super Prev Next

Linker error and warning messages

0
Unable to open file file name
Explanation: The linker can not open a file. It may be locked by another process or does not exist, path may be invalid or there is no enough room on used drive.
Action: Check possible reasons and relink.

1
Unable to write file file name
Explanation: The linker can not write a file. Possible reason is lack of enough room on used drive.
Action: Check it and relink.

2
Unable to read file file name
Explanation:
Action:

3
Insufficient memory
Explanation: There is no enough memory to link successfully.
Action: Close some applications and relink.

5
Invalid system argument
Explanation: Option /SYS is set to invalid value (different from ’W’ or ’C’).
Action: Check option setting validity and relink.

6
Invalid OS version argument
Explanation: OS version is set to invalid value (see option /SYS).
Action: Check option setting validity and relink.

7
Invalid number argument
Explanation: Argument is not valid number (see Setting numeric arguments).
Action: Check argument and relink.

8
Invalid parameter - argument
Explanation: Specified parameter is not valid.
Action: Check parameter and relink.

9
Invalid /ENTRY option
Explanation: Entry point name is not specified in option /ENTRY setting.
Action: Check the specification and relink.

10
Invalid option value - value
Explanation: Option is set to invalid value.
Action: Check setting and relink.

11
Unrecognized option argument - option ignored
Explanation: Specified option is not recognized by the linker and ignored.
Action: Check option setting and relink.

12
No file(s) specified
Explanation: There are no files to link.
Action: Check and relink.

13
No DLL initializing routine
Explanation: DLL initializing routine is not specified or /NOENTRY option is set and there is no export from created library.
Action: Check the specification or setting and relink.

14
No program entry point
Explanation: Program entry point is not specified or /NOENTRY option is set.
Action: Check the specification or setting and relink.

15
Name name was declared in module and in module
Explanation: There are declarations of name in two various modules
Action: Investigate the reasons, correct and relink.

16
Name name was redeclared in module
Explanation: Name was redeclared in module.
Action: Investigate the reasons, correct and relink.

17
Illegal RES file file name - must be 32-bit Microsoft format
Explanation: Specified resource file consists of 32-bit Microsoft format header but its format is not 32-bit Microsoft format.
Action: Check resource file format and relink.

18
Illegal file format - file name
Explanation: Specified file format is not recognized by the liker.
Action: Check the specified file format and relink.

19
Empty file file name
Explanation: Specified file is empty.
Action: Check the specified file and relink.

20
File file name too long
Explanation: There is no enough memory to read specified file.
Action: Komu seichas legko?

21
Duplicate definition for export name name
Explanation: There is duplicate export definition for specified name.
Action: Check command line, .EDF and .OBJ file export specification and relink.

22
Entry point from source ignored, used from source
Explanation: There are two entry point specification, one of them is ignored and the other is used.
Action: To be sure, check entry point specifications and relink if it is needed.

23
File file name - illegal CPU type type
Explanation: Specified file has Common Object File Format and its CPU type is not i386 or UNKNOWN.
Action: Check the specified file and relink.

24
File file name - cannot initialize BSS segment name
Explanation: Specified file consists of uninitialized data segment with initialized data.
Action: Check the specified file and relink.

25
File file name - invalid weak external name
Explanation: Specified file consists of reference to invalid weak exrenal name.
Action: Check the specified file and relink.

26
File file name - illegal symbol index index
Explanation: Specified file cinsists of illegal symbol index.
Action: Check the specified file and relink.

27
File file name - unsupported fixup type type
Explanation: Specified file consists of fixup record of unsupported type.
Action: Check the specified file and relink.

28
File file name - invalid section number
Explanation: Specified file consists of section with invalid number.
Action: Check the specified file and relink.

29
File file name - bad storage class number
Explanation: Specified file consists of bad storage class object.
Action: Check the specified file and relink.

30
File file name - not expected end of file
Explanation: The end of specified file is not expected. Possible reason is the file is corrupt.
Action: Check the specified file and relink.

31
File file name (raw : column) - identifier expected
Explanation: The linker expects an identifier at specified location.
Action: Check the specified file and relink.

32
File file name (raw : column) - string isn’t closed
Explanation: A string beginnig at specified location is not closed.
Action: Check the specified file and relink.

33
File file name (raw : column) - bad ordinal number
Explanation: Bad ordinal number is met at specified location.
Action: Check the specified file and relink.

34
File file name (raw : column) - ordinal number expected
Explanation: Ordinal number is expected at specified location.
Action: Check the specified file and relink.

35
File file name (raw : column) - end of file expected
Explanation: The end of file is expected at specified location.
Action: Check the specified file and relink.

37
File file name - unknown COMDAT length prefix prefix
Explanation:
Action:

38
File file name - invalid entry point
Explanation: There is invalid entry point specification.
Action: Check the specified file or entry point specification and relink.

39
File file name group name - local groups not supported
Explanation: The linker does not support local groups.
Action: Check the specified file and relink.

40
File file name - unsupported group type type
Explanation: There is unsupported group type in soecified file.
Action: Check the specified file and relink.

41
File file name - unknown common type type
Explanation: There is unknown common type in specified file.
Action: Check the specified file and relink.

42
File file name - too much data for segment name
Explanation: Specified segment lenght is not agree with lenght of specified segment data.
Action: Check the specified file and relink.

43
File file name - LINNUM segment not specified
Explanation: There is no segment for specified LINNUM record.
Action: Check the specified file and relink.

44
File file name - fixups in BSS segment name
Explanation: Fixup record for uninitialized data segment is illegal.
Action: Check the specified file and relink.

45
File file name - FIXUP without LEDATA
Explanation: There is no LEDATA for segment referenced by fixup record.
Action: Check the specified file and relink.

46
File file name - unsupported OMF record type
Explanation: There is unsupported OMF record type in specified file.
Action: Check the specified file and relink.

47
Illegal record length
Explanation: OMF record lenght has to be more then 2 bytes.
Action: Check the specified file and relink.

48
Record too long
Explanation: Specified OMF record lenght is too long.
Action: Check the specified file and relink.

49
File file name - unknown record type type
Explanation: There is unknown OMF record type in specified file.
Action: Check the specified file and relink.

50
File file name - internal name name not found
Explanation: Specified internal name is not found.
Action: Check the specified file and relink.

51
File file name - duplicate definition for export name name
Explanation: There is duplicate export definition for specified name.
Action: Check export definitions and relink.

52
File file name - unresolved segment name
Explanation: There is unresolved reference to specified segment.
Action: Check the specified file and relink.

53
Invalid fixup target
Explanation: Specified fixup target is invalid.
Action: ?

54
Invalid fixup for a flat memory model
Explanation: Specified fixup type is not valid for a flat memmory model.
Action: ?

55
Name name not found
Explanation: There is unresolved reference to specified name.
Action: ?

56
Name name not found (referenced in module
Explanation: There is unresolved reference to specified name in specified file.
Action: Check the specified file and relink.

57
Invalid entry point target
Explanation: Entry point specification is invalid (has bad target).
Action: Check a file consisting of entry point specification and relink.

58
Illegal stub file file name
Explanation: Specified stub file is illegal.
Action: Check setting of /STUB option and specified stub file and relink.

61
File file name - unhandled EXE type or invalid EXE
Explanation: Specified DLL has unhandled or invalid format.
Action: Check the specified file and command line specifications and relink.

62
File file name - unable to find EXPORT section
Explanation: Specified dll has no export section.
Action: Check the specified file and command line specifications and relink.

63
Ivalid option option - option skipped
Explanation: set value of specified option is invalid and option setting is skipped.
Action: Check option setting and relink.

64
Ivalid image format format
Explanation: Specified image format is invalid.
Action: Check option /IMAGEFORMAT setting and relink.

65
Unable to mix debug information from modules - module (CV), module (HLL4)
Explanation: At least two modules with deffirent debug information formats are specified to link. The linker can not mix debug information.
Action: Check specified modules and relink.

66
Duplicate debug information for module module
Explanation: There is duplicate debug information for specified module.
Action: Check specified module and relink.

67
File file name - duplicate resource name
Explanation: There is duplicate resource name in specified resource file.
Action: Check the specified file and relink.


Super Prev Next

Using third-party linkers

You may use virtually any third-party linker accepting libraries and object files in either OMF or COFF format (XLINK accepts both). Note, however, that the XDS run-time library is in OMF format; COFF version is available on a special request.

The template file included into your XDS package contains support for some widely used third-party linkers, such as Watcom’s WLINK. Refer to the Read Me First file from your on-line documentation.

Have to write something here.more in readme files. !!!