\documentstyle[a4,12pt]{article}
\begin{document}
\author{APM Manual pages}
\title{The LINK command}
\maketitle
\parskip .1 in
\setcounter{secnumdepth}{10}
\parindent 0in

\section{Preamble}
Owing to incompatibilities between V2 and V3 compilers, two variants of this
command exist:

\hspace*{ 0.4 in} LINK2 for modules compiled by version 2 compilers,
\\ \hspace*{ 0.4 in} LINK3 for modules compiled by version 3 compilers.

At present (September 1986), LINK is equivalent to LINK2.

The parameters to the commands consist of a list of input module names and a
single name to be given to the output module. The file-name extension .MOB is
assumed for all of the names.

\section{Background}
The LINK command combines two or more compiled M68000 program modules into a
single program module. The cross-references between the input modules are
discharged so that they no longer require to be satisfied at execution time.

One of the reasons for carrying out this operation is to reduce the time
overhead in loading a program made up of a large number of fixed modules.
Another is to make a program more self-contained and less dependent on the
module environment in which it is run. Use of it involves sacrificing the
flexibility of load-time linking and convenience of individual module
development, so that it is appropriate mainly for stable program suites.
Note also that, in the case of modules compiled with the V3 diagnostic
compilers, that DIAGNOSTIC INFORMATION IS LOST in the linking process.

If the first input module is a main program, the resultant module will
also be a main program; otherwise the resultant module will simply be a
library of external procedures.

The import list of the output module will consist of all those imports
appearing in the import lists of the input modules which are NOT
satisfied by internal cross-reference.

By default, the export list of the output module will consist of all
those exports which are NOT used to satisfy internal cross-references.

The user may modify this behaviour by requesting that an export should
either be included irrespective (even if used internally) or excluded
irrespective (even if not used internally).

\section{Using LINK2}

\hspace*{ 0.2 in} \} LINK2 Mainfile,Auxfile1,.../Outfile-Options

Up to 19 auxiliary files may be specified.

\subsection{Parameters}

Mainfile
\\ \hspace*{ 0.9 in} The object file containing the main module.

Auxfile1..19
\\ \hspace*{ 0.9 in} Object files containing further modules.

Outfile
\\ \hspace*{ 0.9 in} The file to receive the output object module. If omitted, the
\\ \hspace*{ 0.9 in} output file will have the same name as (i.e. will replace)
\\ \hspace*{ 0.9 in} the main input file.

\subsection{Options}
\subsubsection{Include, Exclude}
These parameters, if present, are either "*" or a filename.
If "*", this means all exports are to be in/excluded in the output,
if a filename (which may be the terminal (":")), then a list of export names
to be in/excluded are read from the specified file.

If one is specified as "*", it will be processed before the other, so that
the other is always a list of exceptions to the first.
Specifying "*" for both is daft.

\subsubsection{Dynamic}
If this boolean parameter is specified, any dynamic references are left
as such. Otherwise these are converted into ordinary external references.

\subsubsection{Auto}
If this boolean parameter is specified, the linker will search the
current external dictionary to determine which object files are required.
This eliminates the need to type in long lists of object filenames,
provided the ones needed have been INSTALLed.

\subsubsection{Disregard}
This parameter (relevant only when -auto is specified), is a filename.
The file contains a list of object file names NOT to be inculded by
the automatic scanning. The default DISREGARD-file is UTILS:LINK.DAT
which causes the linker to exclude most of the standard run time libraries
which are normally preloaded (or at least installed) on all machines.


\subsection{Restrictions}
\subsubsection{Part-linking}
Part-linking a collection of libraries to form a new library is not recommended,
especially if the resultant library is intended to be linked later with
something else. It is therefore suggested that the MAINFILE should always be a
main program.

More precisely, you are likely to get into trouble if any included
exports are not from the first module of the parameter list (Mainfile).

In other words, it should be OK to part-link A with B and C, provided that,
at run-time, the exports made by B and C are only used by A, B, or C, not
by the main program or other modules loaded with it.

\subsubsection{Dynamic references}
Believed dodgy. Hence the -DYNAMIC parameter is off by default.

\subsubsection{Size of output file}
Things may go wrong if the combined size of the output code and data
areas exceeds 64K.



\section{Using LINK3}
Parameters may be provided as part of the command line. If omitted from the
command, they will be requested on subsequent lines, one module per line.

The output file name is mandatory. The command line is NOT processed by PAM.

For example

\hspace*{ 0.2 in} \} LINK3 MAIN,SUB1,SUB2/NEWMAIN

or
\\ \hspace*{ 0.2 in} \} LINK3
\\ \hspace*{ 0.2 in} 1st file: MAIN
\\ \hspace*{ 0.2 in} 2nd file: SUB1
\\ \hspace*{ 0.2 in} 3rd file (or *): SUB2
\\ \hspace*{ 0.2 in} 4th file (or *): *
\\ \hspace*{ 0.2 in} New file: NEWMAIN

\subsection{Include, Exclude}
Inclusions and exclusions are specified by means of a + (inclusion)
or - (exclusion) followed by an export name (or * for all).
For example
\\ \hspace*{ 0.2 in} \} LINK
\\ \hspace*{ 0.2 in} 1st file: MAIN+*
\\ \hspace*{ 0.2 in} 2nd file: SUB1+PARSE-DIAGNOSE
\\ \hspace*{ 0.2 in} 3rd file (or *): SUB2-*+INITIALISE
\\ \hspace*{ 0.4 in} etc

\subsection{Notes}
The process of linking does not alter the main code of the modules,
and the internally linked calls therefore use the same call sequence
as normally linked externals.

A linked module is itself acceptable as input to the LINK program.

If an import name could be satisfied by more than one export
name (by virtue of the presence of multiple exports with the same name)
the one that is used to satisfy the reference is not guaranteed to
match that which would be selected by load-time linking. In general,
this means that such duplication should be avoided.

Multiple occurrences of the same (unsatisfied) import name
will appear multiply in the linked file.

Diagnostic tables do not survive linking.

Automatic linking (as with LINK2) is not available.


\vspace{.75in} view:link printed on 15/02/89 at 21.49

\newpage
\tableofcontents
\end{document}