                               NLMLINK
                           Version 2.82 X2R

                  (C) Copyright 1994 by Novell, Inc.
                         All Rights Reserved.


---------------------------------------------------------------------

NLMLINK versions:

    NLMLINK is now released as three different executables:

            NLMLINKR        DOS real mode - 640 K limit
            NLMLINKX        DOS protected mode - requires DOS4GW
            NLMLINK2        OS/2

    The current version is identified as "2.82 X2R" in the startup
    banner.

    These three executables replace the older NLMLINKP and NLMLINKR.
    NLMLINKP is no longer supported.  NLMLINKX is much more compatible
    with memory managers.  DOS4GW is distributed with the Watcom compiler
    (version 9.0 and beyond) and should be in the search path before
    running NLMLINKX.

    All three executables are produced from the same source code, so
    there should be no functional differences except those imposed by the
    execution environment.

---------------------------------------------------------------------

Documentation:

    See the Software Developer's Kit, NetWare NLM Development and
    Tools Overview, for documentation on NLMLINK parameters.

---------------------------------------------------------------------

Key New Features in this version (New Feature Descriptions below):

  VERSION 2.82

	Description string processes newlines in the string.

	example:  "First Line\nSecond Line"
	is printed on two lines on the console when the NLM is loaded.


  VERSION 2.81

	Changed some WARNING messages to INFORMATION messages so that
	they would be easier to understand and less distracting.

	Added checking for zero length files and improved the error
	messages which result from them.

	Cleaned up several obscure error messages which gave incomplete
	or misleading information.


  VERSION 2.79

    Processes object files produced with the Watcom /d2 switch.

    Processes object files produced by the Borland 386 compiler. 
    This is a side effect of fixing several problems with unrecognized
    object records.

    Allows import/export prefix in symbols lists.

    Some new parameters have been added:

        NAMELEN, PATH, DATASTART, AUTOUNLOAD, STAMPEDDATA, FLAG_ON,
        FLAG_OFF


---------------------------------------------------------------------

Summary of valid def file commands:

(Here <> indicates required parameters, and [] indicates optional
parameters.)

    AUTOUNLOAD       

    CHECK            <check procedure name>

    CODESTART        <map file code start offset (decimal or Xhex)>

    COPYRIGHT        ["Copyright String"]

    CUSTOM           <custom data file path>

    DATASTART        <map file data start offset (decimal or Xhex)>

	DATE			 <month, day, year>

    DEBUG            

    DESCRIPTION      "NLM Description String"

    EXIT             <exit procedure name>

    EXPORT           <symbol list> | @<symbol list file>

    FLAG_OFF         <decimal number>

    FLAG_ON          <decimal number>

    HELP             <help file path>

    IMPORT           <symbol list> | @<symbol list file>

    INPUT            <obj list> | @<obj list file>

    MAP              [map file name]

    MESSAGES         <message file path>

    MODULE           <autoload NLM list>

    MULTIPLE         
                               
    NAMELEN          <decimal number> Default is 31. Zero is no limit.

    OS_DOMAIN        

    OUTPUT           <target file name>

    PATH             [search path;...] for following CUSTOM, HELP, INPUT,

                     MESSAGES, SHARELIB, STAMPEDDATA and XDCDATA.

    PSEUDOPREEMPTION 

    REENTRANT        

    SCREENNAME       "Initial Screen Name (CLIB)"

    SHARELIB         <shared library path>

    STACK            <stack size>

    STACKSIZE        <stack size>

    STAMPEDDATA      "Stamp" (8 char max) <data file path>

    START            <start procedure name>

    SYNCHRONIZE      

    THREADNAME       "Initial Process Name (CLIB)"

    TYPE             <0 - NLM> | <1 - LAN> | <2 - DSK> | <3 - NAM>

    VERSION          <major version>, <minor version> [, <revision>]

    XDCDATA          <XDC data file path>


---------------------------------------------------------------------

New Feature Descriptions:

    PATH command.  Use the path command to avoid having to have a
    complete path specifier on every input file.

    The path command is followed by one or more path
    specifications suitable for prepending to file names.  The paths
    will be searched whenever any "input" file is needed by a future
    command.  Multiple paths may be included by separating them using
    semicolons.  Once the path command is used the current directory
    is not searched unless it is explicitly indicated.  If a file 
    name includes a path then only that path is used.  Examples:

    PATH    OBJ\;.\;    # OBJ first, then the current directory
    PATH    ..\OBJ\;;   # NULL path also searches current directory

    PATH    .\;         # Search only the current directory
    PATH                # No argument also means current directory

    NOTE:  Since the path is only prepended to file names the
    terminating slash is generally essential.


    NAMELEN command.  This establishes the maximum number of
    characters used to match symbol names.  Compilers and assemblers may
    have different defaults, 31 vs. 32, for example.  NAMELEN should be
    set to the smallest value supported by all the tools.  For example:
    NAMELEN 6 means that "ASHORTNAME" and "ASHORTALTERNATIVE" are
    considered the same symbol by the linker.


    DATASTART command.  This command causes the MAP file listing of
    data symbols to show the locations with a fixed offset.  It has
    no effect on the actual NLM.  This command, along with CODESTART,
    is generally used by the OS development team to make their map
    information correspond to the actual addresses where the OS
    is loaded, thus saving them a lot of menial arithmetic during
    debugging.


    AUTOUNLOAD command.  This command sets the autounload bit in the
    NLM header, meaning that the NLM will be unloaded when none of
    the exported symbols are needed by other NLMs.  The feature,
    naturally, requires OS support.

    FLAG_ON and FLAG_OFF commands.  These are alternative methods of
    setting several flags in the NLM header.  These allow new flags
    to be controlled without changing NLMLINK.  The numeric parameter
    is used as a mask to enable or disable the flag bits.  These
    commands can be repeated and the effect is cumulative.  Proper
    use requires knowledge of the bit positions within the flag word.
    For example:  FLAG_ON 64 is equivalent to AUTOUNLOAD.

    STAMPEDDATA is a new keyword which allows arbitrary data to
    be imbedded in an NLM in such a way that other NLM tools are able
    to identify and "pass through" the data.  The parameters are an
    (up to) 8 character signature and a filename.  The stamp is
    placed in a header in the NLM with the following structure and
    the file contents are then added to the NLM.  End users must scan for
    the header and then find and read the data during NLM
    initialization.  This will generally require writing a custom
    prelude, which process is described in the NLM Development and Tools
    overview.

        struct custhead
        {
            char    CUSTHEAD[8];    /* Contains "CuStHeAd"*/
            LONG    HeaderSize      /* size of following data: 16*/
            LONG    DataOffset;     /* offset of data*/
            LONG    DataLength;     /* length of data*/
            char    Signature[8];   /* from the parameter*/
                                    /* right padded with blanks*/   
        };



    /d2 Watcom compiler switch.  You can now compile using the /d2
    switch on the Watcom compiler.  The special debug records
    produced by the compiler are ignored but NLMLINK does not report
    unknown object record types.

    BORLAND compilers.  NLMLINK now links most object files produced
    by the BORLAND 386 compiler.  NLMLINK is not guaranteed to accept
    all Borland object files but seems to do quite well.
    Please report any problems you can't work around.


    Import and export Prefix.  In an import or export list a name
    may be placed in parentheses, as though it were just another
    item.  This "prefix" will be prepended (with '@') to all the
    following symbols in the list.  This allows for multiple NLMs
    exporting essentially the same name; the actual symbols will be
    determined by the prefix.  This is useful for writing shared
    library NLMs, such as CLIB.  For example, in source code "printf"
    may be used as normal and then during the link process resolved
    to "NOVELL@printf", "ALT@printf", or whatever.  Whenever the
    import or export keyword is seen the prefix is nullified; so,
    the prefix must be used in any list to which it applies.  A
    prefix applies to the entries in the list up to the point of the
    next prefix.  A prefix is not required.  A prefix may be canceled
    by coding "()" at some point.  The use of a prefix is thought to
    be backwards compatible with loaders from NetWare version 3.x -
    however, careful testing is recommended.  Example:

        IMPORT  (ALT_PREFIX)
                symbol1     #becomes ALT_PREFIX@symbol1
                symbol2     #becomes ALT_PREFIX@symbol2
                ()          #No prefix on following symbols
                symbol3     #just symbol3

---------------------------------------------------------------------

COMMON QUESTIONS:

    Q. Why does NLMLINK report an unknown object record type and what
    do I do about it?

    A.  NLMLINK isn't really a general purpose linker.  It processes
    object records which we have "seen before."  As compilers change
    they sometimes create object records which have not been
    previously used, and NLMLINK chokes.  Please report these problems
    and supply a sample of the source code which generated the record. 
    We'll try to improve NLMLINK.  

    As an alternative, use the vendor's own NLM linking option (for 
    example, WLINK) whenever you can.  It is likely that the vendor's 
    linker is a better linker than NLMLINK.


    Q. What was the main cause of unknown object records in the past?

    A. Newer compilers started issuing different object records for
    initialized static variables than they had in the past.
    Frequently removing the static declaration would allow older
    versions of NLMLINK to work.  

    Also, use of the /d2 switch on the
    Watcom compiler produced object records which NLMLINK could not
    handle.  These problems have largely been eliminated with version
    2.79.

    Q. Why do I get an error saying that segment FLAT has no records?

    A. You used the Watcom compiler without the /ez switch.  NLMLINK
    expects Easy OMF record formats, which is what /ez produces.

    
    Q. Will NLMLINK work with windows?
                                     
    A. NLMLINKX and NLMLINKR seem to.

