ftp.barnyard.co.uk/2015.02.ftp.barnyard.co.uk.tar/ftp.barnyard.co.uk/cpm/walnut-creek-CDROM/MBUG/MBUG112.ARC/PROLINK.LBR/PROLINK.HYP/PROLINK.HYP

Text File | 1979-12-31 | 22KB | 477 lines

;
           
Prolink (TM) Microsoft Compatible Linkage Editor

0 - Overview                          N - ORIGIN
1 - Command lines                     Q - SETLOC
2 - Expressions and Symbols           V - EVAL
3 - Filenames                         D - DUMP
4 - $MEMRY and ?MEMRY                 P - PATCH
5 - ?BEG? and ?END?                   X - SEED
6 - Re-defineable symbols             Y - SYMFIL
                                      T - SORT
H - HELP and STAT                     G - PURGE
R - READ                              Z - RESOLVE
K - LINK                              U - UNDEF, UNREF, MULDEF, and SYMBOL
L - LOAD                              F - DEFINE and REDEF
S - SEARCH                            W - WRSYM
O - OUTFIL                            A - ABORT and RESET
E - EXIT and CLOSE
: 0
                                   
Overview

ProLink is a Microsoft-format linkage editor for computers employing the Z80
microprocessor and running CP/M and compatible operating systems.

ProLink is a command-driven linker, and provides an interactive environment for
the generation of object program modules.  In addition to the basic link and
library search commands, ProLink provides an array of commands for symbol file
control, object module placement, "hot-patching" the object image, automatic
operation from batch execution files, "add-on" modules, and more.

ProLink is an in-memory single pass linkage editor, and is thus quite fast; it
is intended strictly for assembly-language modules (rather than "high-level"
compiler output, which is NOT supported by ProLink) and supports all Microsoft-
format relocation bases.
: 1
                                
Command lines

When ProLink is initially invoked (by typing PROLINK at the CP/M command
prompt), you may optionally specify a command line to be executed when ProLink
loads.    For example, from CP/M command level, you might type

              PROLINK LINK FOO;EXIT

Note that everything after "PROLINK" is an input command line to ProLink, and
is executed just as if you had typed it at the ProLink command prompt.    All
ProLink commands are valid from the CP/M command line; when any such command
line is completed (or if no command line is entered) you'll see the ProLink
input prompt (the '*' character), which is ProLink's signal that it's ready to
accept another line of input. (Note that an "EXIT" command in the input stream,
as is given in the example above, will cause ProLink to write its output file
and return immediately to CP/M, without prompting you for any additional
input).
: 2
                           
Expressions and Symbols

ProLink expressions are integer numbers; the components (and the result of
evaluation) are unsigned 16-bit integers.  Valid operators are "+", "-", "*"
and "/" (add, subtract, multiply, divide).  Symbol names (from any linked
modules already in memory) may also be included.  Thus, the following are legal
expressions:

                PATCH+3
                NMEMPL/4
                6*8+9
                ((NMEMPL+3)/(6+9)+1)/8

It is important to note that numeric constants are considered to be hexadecimal
as a default.  To avoid confusion with symbols, all constants beginning with
letters 'A' to 'F' should be preceeded with a leading zero (thus, 0FFA1, not
FFA1; the latter would be interpreted by ProLink as a symbol).    You can specify
a decimal number by preceeding the number with a pound sign ("#"); thus the
constant 10 is 10 hex, or 16 decimal, while #10 is 10 decimal, or 0A hex.
: 3
                                  
Filenames

Any file specification may be preceeded with a user number, as long as a colon
separates the file name from the user specification.  This holds true whether
or not a drive specification is also present (this is often called the "ZCPR
style" naming convention).  Thus the following are legal filenames:

              B3:OBJECT.REL
              C:MXO-SM13.HEX
              3:SYSLIB.REL
: N
                              
The ORIGIN command

ORIGIN is used to set the beginning address of your output file.  By setting an
ORIGIN, you change the EXECUTION ADDRESS of the output code, but NOT its
position in the output file (that is, the first byte of output still occupies
the first position in the output file).

If you don't specify an ORIGIN address, ProLink will default to 100H.  You
should be aware that ProLink's default origin will include a 3-byte jump field
at 100H that is filled in with a jump to your program's entry point at linkage
time. If you change the origin, ProLink will not generate this jump
instruction, and the code segment (CSEG) of your first module must begin your
program.

Occasionally, you'll want to defeat this jump-field generation, even when
loading programs at 100H (for example, Echelon's ZCPR3 utilities must start at
exactly 100H, without the jump field).    You can do this by explicitly setting
the origin:

               ORIGIN 100
: K
                               
The LINK command

The most fundamental command of ProLink's set is the LINK command.  Its syntax
is:

    LINK <module-name>[,<module-name>] ...

You can link several files with one LINK command:

         LINK FOO,MATHPAK,IOPACK,FORMAT

Multiple link commands may be used instead, with the same result.
: S
                              
The SEARCH command

Use the SEARCH command after one or more LINK commands, to "pull in" often-used
routines from your library of code modules.  For example,

              LINK DBSEARCH,FNPARS
              SEARCH SYSLIB

In this example, DBSEARCH.REL and FNPARS.REL are unconditionally linked into
the output file, and SYSLIB.REL is searched for needed subroutines to satisfy
unresolved references from DBSEARCH and FNPARS.

If your assembler supports a library-search pseudo-op (e.g., ".REQUEST" in
Microsoft's MACRO-80 assembler), ProLink will automatically search all such
requested libraries just prior to closing the output file (with the CLOSE or
EXIT commands).  To use this feature, the requested libraries must be available
on the current drive, in the current user area.
: L
                               
The LOAD command

The LOAD command is used to load Intel "hex" format files, binary "image"
files, or symbol files.  Its syntax is as follows:

     LOAD <filename.typ>[,<filename.typ>] ...

LOAD uses the filetype to distinguish "hex", binary, and symbol files.    The
default type is HEX.

If you specify "SYM" as a filetype, LOAD will load symbols into its internal
symbol table.  Note that symbol files written by ProLink are fully compatible
with this format; thus, SYM files written by ProLink may be safely reloaded in
a later ProLink session, or used under Digital Research's SID or ZSID
debuggers.

Any filetype other than HEX or SYM (or blank) will be considered an "image"
file.  Typically these are COM files, but can also be overlay files, or even
ASCII text files.  Image files are loaded into memory starting at the current
PC value (viewable with the STAT command, and changeable with the SETLOC
command), and must fit in available memory
: A
                         
The ABORT and RESET commands

The ABORT command exits the current session, without writing a file or
otherwise disturbing anything on the disk.

During a linkage session, you might find that you want to start over for some
reason.  The RESET command will restore ProLink to its start-up state; any
program currently being linked will be removed from memory, and ProLink's
internal variables (including the default value of ORIGIN) will be reset.

The RESET and ABORT commands takes no command line arguments.
: O
                              
The OUTFIL command

The OUTFIL command is used to specify a name for your output file.  Its syntax
is as follows:

            OUTFIL <filename>

If you omit the OUTFIL command, ProLink will build an output name using the
name of your first input file: it will use the first eight characters of that
name, stripping off the filetype (generally "REL") and forming a filetype of
"COM".
: E
                  
Closing the edit: EXIT and CLOSE commands

EXIT is the "normal" method of ending the linkage; it writes the output file,
and exits to CP/M.

CLOSE will write the output file in the same way, but, instead of exiting to
CP/M, ProLink will do an automatic RESET command and return to command level.
Thus, you're ready for another linkage session.

The syntax is identical for CLOSE and EXIT, and is illustrated here for CLOSE:

               CLOSE [<filename>]

The optional filename overrides any name that may have been specified with the
OUTFIL command.

Both EXIT and CLOSE will print a list of any unresolved symbols (if any remain
unresolved), as well as a list of multiply-defined symbols (if multiply defined
symbols exist).  Following any such list, ProLink will print a one-line message
containing the starting and ending addresses, followed by the size of the
output file (in 256-byte pages).
: R
                   
Automating the process: the READ command

The syntax of the READ command is as follows:

              READ <filename> [$E]

ProLink will then take its input from the specified file.  Note that, if no
filetype is specified, ProLink will look for a file of type "LNK".  Thus, you
should create READ files with a "LNK" filetype.

Normally, ProLink will not echo the command lines it is executing from a READ
file.  However, the "$E" option will override this, and each command will be
displayed on your screen just prior to its execution (this is especially useful
when "debugging" a READ file).

A READ file may contain any valid ProLink command EXCEPT another READ command
(i.e., READ files may not be nested).

You can place a comment within a READ file (or at command level from the
keyboard, for that matter) by placing a period (".") in the first character
position of a line.
: H
                          
The HELP and STAT commands

HELP prints a list of available commands on the screen.  Useful as a memory
jogger, but it doesn't give any information about command syntax.  You'll have
to refer to the User's Guide for that.

STAT may be used to display the status of the linkage at any particular time.
STAT prints information such as output filename, symbol filename, state of the
linkage, memory statistics, etc.

HELP and STAT do not take any command line arguments.
: V
                               
The EVAL command

EVAL is a general-purpose expression evaluator.  Its syntax is

          EVAL <expression>[,<expression>] ...

EVAL is most useful for determining symbol values, but it can also come in
handy for doing quick arithmetic calculations.

EVAL prints its result both in hexadecimal and decimal (the decimal value is
printed with a leading pound sign).
: D
                               
The DUMP command

DUMP displays memory from the image under construction, in the DDT-style
combined hex and ASCII.  The syntax for the DUMP command is

          DUMP [<start-adrs>] [+][<end-address>]

If no start or end address is entered, DUMP will display from the previous
ending DUMP address (or the program origin if no previous DUMP has been
performed) for a length of 128 bytes.  If a start-address is entered without an
ending address, 128 bytes will be displayed.  The ending address prefixed with
the optional '+' specifier causes the end-address to be considered a count of
bytes to display, rather than an actual ending address.

Note that "D" is a shorthand synonym for "DUMP".
: Y
                              
The SYMFIL command

SYMFIL is used to specify a symbol file name, to turn on the symbol file
(ProLink, as a default, does not write a symbol file), and to control the "X"
symbol option.    Its syntax is

          SYMFIL [<filespec>] [$ON] [$OFF] [$X]

At least one of the four optional arguments must be present, and no more than
one of the "$" options may be present in a single command line.

The <filespec> field is used to change the name of the symbol file written by
ProLink; just specifying the name, however, does not cause ProLink to write a
symbol file: the "$ON" option must be used for this.

If no filespec is entered, ProLink will generate its own name, using the first
eight characters of the output file name, with "SYM" appended as the filetype.

The "$X" option toggles the x-symbol option on and off.
: U
                
The UNDEF, UNREF, MULDEF, and SYMBOL commands

The UNDEF command may be used at any time to display all undefined symbols on
the terminal.  An automatic UNDEF is done when the output file is written, if
any undefined symbols exist.

The UNREF command displays on the terminal a list of symbols that are defined,
but not referenced.  This is useful for detecting blocks of code that are no
longer referenced globally (if they are not referenced in the module in which
they are defined, they may then be safely deleted).  Such symbols, if
referenced in their local modules, may have their global attribute removed.

The MULDEF command is used to display any multiply-defined symbols on the
terminal.  An automatic MULDEF is done when the output file is written, if any
multiply-defined symbols exist.

The SYMBOL command is used to display the current symbol table on the terminal.
Note that "SYMBOLS" is a synonym for "SYMBOL", and that the command takes no
command line arguments.
: T
                    
Sorting the symbols: the SORT command

As a default, ProLink does not sort its symbols, but writes them in the order
in which they are encountered.    Some symbolic debuggers require a sorted symbol
table, and you can use the SORT command to accomplish this.

SORT uses a simple bubble sort, and may take long periods of time with large
symbol tables.    You may safely stop the sort at any time with a control-C from
the keyboard, without damage to the symbol table.

SORT takes no command line options.
: F
                        
The DEFINE and REDEF commands

Occasionally, you might find the need to add your own symbols, or redefine
existing ones.    The DEFINE and REDEF commands provide this capability.    Both
commands take the same command line syntax, which we'll specify only for
DEFINE, as follows:

        DEFINE <symbol-name> <expression>

The DEFINE command requires that the symbol-name specified be either non-
existant, or non-defined; the latter implies that the symbol can exist in the
table by virtue of previous references by other modules, but that it must not
yet be defined.  If <symbol-name> IS defined, the DEFINE command will draw an
error message, and the symbol's value will not be changed.  Note that if no
references exist, DEFINE will create a new entry for the symbol, and then
define it with a value specified by <expression>.

The REDEF command requires that the argument symbol-name be an existing,
defined symbol; if it is non-existant (or not defined), the REDEF command cause
an error message, but no new symbol will be created.  If <symbol-name> is
found, the old value will be lost, and the new value (specified by
<expression>) will be substituted in its place.
: G
                              
The PURGE command

The PURGE command is used to delete symbols from the symbol table.  Its syntax
is

         PURGE <symbol-name>[,<symbol-name>] ...

PURGE will delete each of the symbols from the list, including any references
to the symbol (i.e., if you PURGE a symbol, you remove not only its definition,
but any references ProLink has formed for the symbol.  So unless you load new
modules with references to a purged symbol AFTER a purge, ProLink will not
issue a "not-defined" diagnostic when the output file is written).

PURGE will print a "not-found" message for any symbols in the list that it
can't locate; this will not, however, stop the PURGE command: it will continue
with any remaining symbols in the list.
: W
                              
The WRSYM command

The WRSYM command writes out the current symbol table to a disk file.  It takes
an optional filename argument:

               WRSYM [<filename>]

Note that if a <filename> spec is present, this name overrides any filename
specified by the SYMFIL command (which is used if <filename> is omitted).
Also, a filename specified to WRSYM changes any SYMFIL-specified name.
: 4
                              
$MEMRY and ?MEMRY

$MEMRY is a special variable name recognized by most Microsoft-compatible
linkers, and must be a 2-byte storage area within any of the linked object
modules.  On encountering this symbol, ProLink will insert the first free
memory address at this word location.  Thus, a "main" module may include

              PUBLIC $MEMRY
              ....
              $MEMRY: DS 2

The base address of free memory is then available to all object modules by
performing

               LHLD $MEMRY
: 5
                               
?BEG? and ?END?

The symbol '?BEG?' contains the base address of the linked output image;
'?END?' contains the ending address (which is actually the base of the "free"
area).    Thus, rather than loading a word value from memory to locate the base
of the free area (as is done with $MEMRY and ?MEMRY), you simply reference
?END?.    For example,

            EXTRN ?END?,?BEG?
            LXI H,?END?
            LXI D,?BEG?

In this example, HL obtains the end of linked program, and DE the beginning.
: 6
                            
Re-defineable symbols

ProLink supports a special kind of symbol, called a re-defineable symbol.  Such
a symbol may be defined more than once, and each succeeding definition
definition will map to a unique symbol.

Re-defineable symbols always end with the special character '@'; the first
definition of such a symbol maps the '@' character to the character 'A', the
second to 'B', and so on.  This lets you have multiple (and likely, similar)
modules, each with an identical entry name, say "TRMDR@" (one might be for an
ADM3A, another for a Hazeltine 1500, etc).  The first module encountered with
such a name will be redefined by ProLink to have the name "TRMDRA", the second,
"TRMDRB", etc.    Each module might have an initialization entry point with a re-
defineable symbol; thus "TINIT@" would be re-defined by ProLink as TINITA,
TINITB, etc.
: P
                    
Modifying the image: the PATCH command

Once your program is loaded, and resident in ProLink's memory, you can make
changes to the generated image by using the PATCH command.  The syntax of the
PATCH command is as follows:

   PATCH [<adrs-expression>]=<patch-value>[,<patch-value>] ...

The <adrs-expression> specifies where to begin patching the image; usually,
this expression will be given relative to a global symbol name (e.g.,
CMDTBL+3).  <adrs-expression> is NOT optional on the first PATCH command of a
session; after that, the PATCH command will remember where the last patch
ended, and continue patching at the next successive location (unless a new
address is specified by NOT omitting <adrs-expression>.

Byte expressions, word expressions, and strings may be freely intermixed:

       PATCH CMDTBL="DUMP",DUMPCM,"GOTO",GOTOCM,0
       PATCH SOMESG="Version 1.0",0,NXTMSG
: X
                               
The SEED command

Generally, the SEED value used with the 'X' option of the SYMFIL command (see
description in the preceeding section) is set to the value of the symbol ?END?
plus one.  You can use the SEED command, however, to provide your own starting
SEED value.   The syntax of the SEED command is as follows:

            SEED <expression>

where <expression> is the initial value you want to use for seed.
: Z
                     
Modular add-ons: the RESOLVE command

ProLink supports a modular programming contruct that, while it must be used
with great care, encourages the use of "add-on" code blocks that may be added
or removed at will, and thus produce custom or specialized versions of your
programs, without the cumbersome and error-prone conditional assembly
techniques that have traditionally been used for this purpose.    This construct
is embodied in the RESOLVE command.

              RESOLVE <symbol-name>

Basicly, the RESOLVE command specifies a symbol that is used to resolve ALL
otherwise undefined globals, at the conclusion of the linkage editing session.
: Q
                              
The SETLOC command

               SETLOC <expression>

Generally, the location counter should be considered the "next" load address;
at start-up, its value is the same as ORIGIN (if you specified an origin; if
not, the default origin is 100H, but the location counter is set to 103H, to
leave room for the ProLink-generated jump to your program's entry point).
After using one of the LINK, SEARCH or LOAD commands to load a module into
memory, ProLink will move the location counter up to the first free memory cell
AFTER the loaded module.  The next LINK, SEARCH or LOAD command will then begin
loading immediately after the first.

Using the SETLOC command, however, you may freely change this "next-load"
location.  You might move it backward, to overload a new module in an area of
an old.  Or you can move it forward, creating a "hole" in the generated image.