X-Hacker.org- The Guide To Clipper - <b>plink86-plus linker for creating overlays</b>
[<<Previous Entry] [^^Up^^] [Next Entry>>] [Menu] [About The Guide]
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
.
Online resources provided by: http://www.X-Hacker.org --- NG 2 HTML conversion by Dave Pearson