\input{read_general:[procedures]sesdfmt.tex} 	% Latex input file defining standard format

\newcommand{\revision} {A}			% latest revision letter
						% (e.g., A, B)
						% (seldom changes)
						
\newcommand{\version} {1}			% latest version 
% UPDATE THE VERSION EACH TIME THE DOCUMENT IS CHANGED, INCREMENTING BY 1
% STARTING WITH VERSION 1

\newcommand{\runningtitle}{Link Check Tool} 		% title for top of page
\newcommand{\control} { SCI89143 }			% ST ScI control number
\newcommand{\modname} {{\bf link\_check.tex}}		% file name in library
\newcommand{\modlibe} {{\bf read\_tools:[sogs] }}	% BROWSE directory
\newcommand{\lnkchk}   {{\it Link Check \/}}    

\thispagestyle{empty}			% No header or number on first page
\markright{\runningtitle \hspace{1.0in} \revision \hspace{0.1in} \version 
\hspace{0.5in}}

\begin{document}
\vspace*{1in} 
\begin{center} 

{\Large{\bf Link Check Tool}}\footnote{This is module \modname{} in 
library \modlibe{}, printed \today} \\

\bigskip
\begin{bf} 
\control \\
\revision\\ 
\bigskip 
\end{bf} 
\author \\ 
\bigskip
\vspace*{2.0in}
{\bf Abstract } \\
\bigskip
\end{center}

% FILL IN AN ABSTRACT 
% This is an abstract of the whole document. It should never be more than a 
% few sentences.

The \lnkchk tool verifies the existence of all input files on a link command,
passing the command onto the Linker if all inputs exist.

\clearpage				% Table of Contents page

\tableofcontents

\clearpage

\section{Introduction}

The \lnkchk tool verifies the existence of all input files on a link command,
passing the command onto the Linker if all inputs exist.  \lnkchk 
is a workaround for a bug in the Linker that 
causes it to go into an endless loop when processing 
many objects with logical searchlists when one of the objects
is missing (either from the command line or an options file).

This tool verifies all linker input files for existence:
\begin{verbatim}
               Object Files     (no qualifier)
               Library Files    (/LIBRARY or /INCLUDE)
               Options Files    (/OPTIONS)
\end{verbatim}

In the case of OPTIONs files, it calls a tool called
{\it OPTCHECK \/} that verifies the existence of all object files 
in a link options file.

\section{Error Reporting}

The VMS message utility is used to report any files that 
do not exist (also used by {\it OPTCHECK\/}).  One error message
per missing file is generated and a fatal exit error 
message is generated when the program terminates if any
files were missing. 

When a logical searchlist is used to find a file, and the file does
not exist, the error message will state that file was not found in
the last directory in the searchlist.

\lnkchk error messages look something like this:
\bigskip
{\small
 \begin{verbatim}
%LNKCHK-E-NOOBJECT, Object file DISK$DINOSAUR:[ANYBODY.ANYDIR]ANY.OBJ; not found

%LNKCHK-E-NOOPTIONS, Options file DISK$DINOSAUR:[ANYBODY.ANYDIR]ANY.OPT; not found

%LNKCHK-E-NOLIBRARY, Library file DISK$DINOSAUR:[ANYBODY.ANYDIR]ANY.OLB; not found

%LNKCHK-F-MISSING, Link statement has missing files, command NOT passed onto Linker

%LNKCHK-S-NOPASS, All Linker inputs exist, /NOPASS so not passing onto linker
 \end{verbatim}
}

And {\it OPTCHECK \/} error messages will look like this:
\bigskip
{\small
 \begin{verbatim}
%OPTCHK-E-OPENIN, error opening DISK$DINOSAUR:[ANYBODY.ANYDIR]ANY.OBJ; as input
 \end{verbatim}
}


\section{Invoking the Link Check Tool}

Use the following command to invoke the \lnkchk tool:
\bigskip
\begin{verbatim}
           $ SET COMMAND SOGSTOOLS:LNKCHK
           $ LNKCHK [</NOPASS>]
                    <Any-Valid-Link-Command>
\end{verbatim}
\bigskip

$<$/NOPASS$>$ is an optional parameter that is applicable to the
\lnkchk tool only.  It tells the tool not to pass the command
onto the Linker if everything checks out but rather only acts as
a Linker input verifier and nothing more.

$<$Any-Valid-Link-Command$>$ means that the syntax of the LNKCHK command
is {\bf identical \/} to the LINK command except LNKCHK is substituted for
LINK.  This includes any qualifiers.  Remember that if all files exist
the command LNKCHK will be changed to LINK and executed.

\subsection{Examples}

Some sample invocations follow:

{\small
 \begin{verbatim}

      $ LNKCHK  spss_object:any_spss_object, oss_object:any_oss_object.obj,-
                any.opt/OPTIONS, any.olb/LIBRARY


      $ LNKCHK/NOPASS  spss_object:any_spss_object, -
                       oss_object:any_oss_object.obj,-
                       any.opt/OPTIONS, any.olb/LIBRARY


      $ LNKCHK/MAP/NOTRACE/CONTIG  spss_object:any_spss_object, -
                       any.opt/OPTIONS, any.olb/LIBRARY /EXEC=ANY.EXE -
                       /FULL

 \end{verbatim}
}

\section{About the Software}

There are 6 files that are associated with this tool:
\bigskip

\begin{enumerate}
\item {\it LNKCHK.MMS \/}

This MMS file maintains the \lnkchk software executable 
{\it LNKCHK.EXE \/}.

\item {\it LNKCHK.CLD \/}

This command definition file is almost exact copy of the LINK command 
with the /NOPASS qualifier added.

\item {\it LNKCHK\_TEST\_LINK.SCN \/}

This is the main program for this tool.  It uses the CLI\$ utilities
to extract Linker input files and their possible qualifiers to check if they
exist or not.

\item {\it LNKCHK\_MESSAGES.MSG \/}

This is the list of VMS error messages for the \lnkchk tool.

\item {\it LNKCHK\_OPTCHECKMAIN.FOR \/}

This is a FORTRAN function that performs the options file checking.
It is an offshoot of the {\it OPTCHECK \/} tool.

\item {\it LNKCHK\_OTHER\_OPTCHECK\_FILES.OPT \/}

This options file contains all necessary object files from the 
{\it OPTCHECK \/} tool that need to be linked in in order
to call it as a function in above routine.

\end{enumerate}
\end{document}