Click above to get retro games delivered to your door ever month!

PLINK86-Plus           Linker for creating overlays


Syntax:        PLINK86 <statements>/@<response file>

Commands:      <response file> is the name of the file containing
               PLINK86-Plus commands.  A .LNK filename extension is
               assumed unless otherwise specified.  The "@" symbol is
               required to indicate that the filename following is a
               response file.  Note that a response file can include an
               optional drive and path designator.

               . A response file can be specified anywhere on a command
                 line
               . References to response files can be nested up to three
                 levels deep
               . Several response files may be specified on the same
                 command line
               . Response files can be mixed with other PLINK86-Plus
                 commands

               <statements> and their arguments communicate the
               required operations and information to PLINK86-Plus.

               #

               Comment symbol.

               ; 

               Ends an interactive session.

               ALLOCATE <library1> [,<library2> ,...]

               Automatically places modules in the specified libraries
               in the overlay structure at locations where they are
               needed.  This action eliminates the need to link the
               entire library into the root overlay.

               BATCH

               Causes PLINK86-Plus to terminate with a fatal error if it
               cannot find a specified .OBJ or .LIB file.  If BATCH is
               not specified, you are prompted when a file is not found.

               BEGINAREA/BEGIN

               Defines the start of an overlay area.  Each overlay area
               contains one or more sections as defined by SECTION FILE
               statement.

               Each BEGINAREA statement must have an accompanying
               ENDAREA statement.

               CACHE [P]<max cache size>
               [,[P]<min program requirement>]

               Creates an overlay cache in available memory under DOS
               2.XX or later.  Both arguments are measured in the
               percentage of available free memory.  If the the "P"
               option is specified, both arguments represent the number
               of 16-byte paragraphs in hex.

               The <max cache size> specifies the amount of memory that
               can be allocated to the overlay cache including any or
               all of extended memory.  The <min program size> specifies
               the minimum memory required to execute the program above
               the memory required to load.

               DEBUG

               Displays the name of the overlay as it is loaded during
               program execution.  It is used to provide information
               when debugging linked programs.

               DEFINE <symbol>=<value>

               Resolves a reference to an external symbol by assigning a
               new value to the symbol.

               ENDAREA/END

               Defines the end of an overlay area starting with the
               BEGINAREA statement.

               FILE/FI <object file list>

               Identifies a list of object files to link.  If more than
               one object file is listed, separate each file reference
               with a comma.  Note that the .OBJ extension is not
               necessary.  In addition, drive and path designators are
               optional.

               If no drive or directory is specified, PLINK86-Plus
               searches for the specified object file as follows:

               . The current directory
               . The path specified in the DOS environmental variable
                 OBJ

               Note: The first object file you link, in any of the
               three methods below, must be Clipper-compiled.  Any
               others compiled by another compiler must be listed
               secondarily.

               HEIGHT <num>

               Sets the page length of the memory map report (MAP) to
               <num>.  The default is 65.

               LIBRARY/LIB <library file list>

               Identifies the list of runtime libraries required to link
               the specified object files.  The default extension is
               .LIB.  If CLIPPER.LIB is not specified, PLINK86-Plus
               looks for it by default.

               If no drive or directory is specified, PLINK86-Plus
               searches for the library as follows:

               . The current directory
               . The path specified in the DOS environmental variables
                 LIB or OBJ

               Note: EXTEND.LIB must be specified to link object
               modules from it.

               LOWERCASE

               Translates all identifiers and symbol names to
               lowercase.  PLINK86-Plus uses the original casing by
               default.

               MAP [= <map filename>] <option list>

               Produces a memory map report describing the output of the
               link including memory usage, size and location
               information.  The <map filename> is the name of the
               report file.  If no extension is specified, PLINK86-Plus
               supplies a .MAP extension.  If no <map filename> is
               specified, output is to the console.

               The following is a list of options that provide more
               detailed MAP information:

               Table: MAP Options
               ------------------------------------------------------
               Option         Meaning
               ------------------------------------------------------
               A              Lists program sections and segments for
                              all sections
               G              Lists all global public symbols with
                              addresses
               M              Lists all modules including module
                              segments and symbols with addresses
               S              Lists all program sections with summary
                              info
               -------------------------------------------------------

               If no option is specified, the "A" option listing is
               produced.

               MIXCASE

               Process all identifiers in their original case.

               MODULE <module name list>

               Assigns all segments from the specified modules to the
               current section which can be an overlay.  This statement
               is useful for placing modules from a library into
               different sections.

               NOBELL

               Suppresses the sounding of the bell when PLINK86-Plus
               displays a message.

               NODEFLIB

               Suppresses any automatic library search requests imbedded
               in an object module by the compiler of the object module.

               NWIDTH <num>

               Specifies the width of identifiers and symbol names when
               printed in a MAP report.  The default width is nine
               characters.

               OUTPUT <filename>[.EXE/.OBJ] 

               Specifies the name of the executable file.  If no
               extension is supplied, the default is .EXE.  If this
               command is not specified, the executable filename will be
               the name of the first object file specified as an
               argument of FILE.

               If the file is specified with an .OBJ extension
               PLINK86-Plus creates a merged object file from the
               current FILE list.

               OVERLAY <class name list>

               Specifies the names of segment classes allowed to remain
               in the overlay structure.

               PRELOAD

               Instructs the overlay loader to load a specified section
               into memory before passing control to the user program.

               SEARCH <library file list>

               The same as the LIBRARY command but causes PLINK86-Plus
               to make multiple passes through the specified library
               files if undefined symbols remain after the files have
               been read.

               SECTION FILE <object file list> [PRELOAD] [INTO
               <overlay filename>] [= <section name>]

               Identifies the <object file list> as those modules to be
               placed into an overlay area.  If the INTO clause is
               specified, the overlay area is external and placed in the
               disk file specified by <overlay filename>.  Otherwise the
               overlay is internal and placed in the main .EXE file.

               If the PRELOAD statement is specified, the specified
               section is loaded into memory at the same time as the
               root section when the load module is executed.

               If the optional <section name> is specified, the name is
               displayed in the MAP reports.

               Note that SECTION FILE statements must be specified
               within a BEGINAREA...ENDAREA construct.

               STACK <number of bytes>

               Changes the size of the stack defined in the .EXE header
               to <number of bytes>.

               Note: <number of bytes> is specified as a hexadecimal
               value.  800 hex is the default.

               UPPERCASE 

               Translates all identifiers and symbols to uppercase.

               VERBOSE

               Displays a message indicating the current PLINK86-Plus
               operation to the screen.

               Note: VERBOSE displays consecutive messages to the
               same screen line making redirection either to the printer
               or a file inappropriate.

               WIDTH <num>

               Sets the line length of the memory map report (MAP) to
               <num>.  The default is 80 characters.

               WORKFILE = <filename>

               Redirects the PLINK86-Plus interim disk file to
               <filename> located in an optional drive and directory
               location, if there is not enough memory available for a
               successful link.

Description:   There are three modes PLINK86-Plus uses to link:

               . Interactively
               . Command line
               . Response file (.LNK file)

               If an error occurs during the linking process, an error
               message or warning is displayed on the screen.

               At the end of a successful linking session, PLINK86-Plus
               will display a message like the following:

                    TEST.EXE (202 K)

               This indicates that the output program was successfully
               created.  The  number in parentheses is the amount of
               memory required before the linked program can be loaded
               for execution.  This size may be different from the
               actual size of the program on disk, especially when
               overlays are used.  It also does not allow for the fact
               that the program will attempt to allocate more memory at
               execution time.  Add 64-100K bytes to the executable file
               size and the result will be the minimum amount of memory
               required to run your application program.  (Use the DOS
               CHKDSK command to ascertain the available memory.)

               This version of PLINK86-Plus is a special version for
               users of the Nantucket compiler.  It provides all the
               major features of PLINK86-Plus, version 2.21.

               Note: The first object file you link, in any of the
               three methods below, must be Clipper-compiled.  Any
               others compiled by another compiler must be listed
               secondarily.

               Interactive Mode: PLINK86-Plus can accept input
               interactively.  To use this method just enter "PLINK86"
               and press Return.  The linker loads and the following
               command prompt appears:

                =>

               You may enter a single command at the prompt and press
               Return, or you may enter several commands on the same
               line and then press Return.  Each time you press Return,
               the command prompt will appear on the next line awaiting
               your entry.  To end the linking session, type a semicolon
               and press Return.

               For example, the linker instructions below produce an
               executable file named TEST.EXE.

                => FILE TEST, PROG1, PROG2
                => LIBRARY CLIPPER, EXTEND
                =>  ;

               Command line mode: The simplest way to run the linker
               is to identify the required information on the linker
               command line and press Return.

Notes:         . Trapping linker errors in a file: If you wish, you
                 may use the DOS output redirection feature by adding ">
                 filename" to the end of the linker command line.  For
                 example:

                    C>PLINK86 FI TEST > LINKERR
                    C>PLINK86 @MYLIST > LINKERR

               . Support: If you receive a warning or error message
                 and are unable to resolve the problem, contact
                 Nantucket Support.  DO NOT contact Phoenix
                 Technologies, Ltd.

               . Case sensitivity: PLINK86-Plus is CASE SENSITIVE.
                 It is a good idea to make all PLINK86-Plus commands
                 upper case.  Check your PLINK86-Plus link files for the
                 following "gotchas."  In all cases, adding
                 LOWERCASE/UPPERCASE to the link file will solve the
                 initial incompatibilities.

                 . OVERLAY command: "overlay code" should be "OVERLAY
                   CODE".

                 . A library with lower case symbols and an upper case
                   index.

                 . Combining assembler with a case sensitive, high level
                   language.  Microsoft MASM forces all symbols to upper
                   case.  If the high level source code refers to those
                   symbols in lower case, turn off case sensitivity with
                   the LOWERCASE or the UPPERCASE command.

               . Linking the Debugger: To include the Debugger in
                 your executable file, identify DEBUG.OBJ as one of the
                 files to be linked.  The only requirement is that your
                 Clipper-compiled program is specified first.

               . OVERLAY.LIB: Do not specify OVERLAY.LIB as an
                 argument of the LIBRARY statement.  PLINK86-Plus looks
                 for it automatically.

               . Mixing libraries and object files across versions:
                 Do not link using either libraries or object files
                 compiled with versions of Clipper prior to Summer '87.
                 The current libraries supplied with Summer '87 are
                 CLIPPER.LIB and EXTEND.LIB.  Program files compiled
                 with previous versions must be recompiled using Clipper
                 Summer '87.

               . Symbol $OVIN$ is missing: In the 12:00am version of
                 Summer '87 PLINK86-Plus, using the DEBUG statement
                 required the symbol, $OVLYVD, redefined as follows:

                    DEFINE  $OVLYVD=$OVLYMD

                 In the 2:00am version of Summer '87 PLINK86-Plus, this
                 redefinition is no longer required.  If, however, you
                 receive the error message, "Symbol $OVIN$ is missing
                 from overlay loader," remove the DEFINE statement from
                 you link command line or response file.

----------------------------------- Example --------------------------------

   1. MYLIST.LNK contains:

   OUTPUT TEST.EXE
   FI TEST @MYLIST2.LNK

   MYLIST2.LNK contains:

   FI TEST2
   LIB CLIPPER, EXTEND

   When you execute PLINK86-Plus by typing:

   C> PLINK86 @MYLIST

   The result is the same as if you had typed:

   OUTPUT TEST.EXE
   FI TEST.OBJ
   FI TEST2.OBJ
   LIB CLIPPER, EXTEND

   2. .LNK files may also be mixed with other PLINK86-Plus commands.
       For example:

   C>PLINK86 @MYLIST VERBOSE

   initiates the linking process and invokes the VERBOSE command.

   3. Set DOS environment for subsequent linking

   C>SET OBJ=\CLIPPER\PROGS
   C>SET LIB=\CLIPPER\LIBS

   Then sometime later

   D>PLINK86 FI APP LIB EXTEND,NETLIB

.