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

\newcommand{\revision} {A}			% latest revision letter
						
\newcommand{\version} {1}			% latest version 
% UPDATE THE VERSION EACH TIME THE DOCUMENT IS CHANGED, INCREMENTING BY 1
% STARTING WITH VERSION 1

\newcommand{\runningtitle}{Check Map Tool}  	% title for top of page
\newcommand{\control} {SCI89139}	% ST ScI control number
\newcommand{\checkmap} {{\it Check Map \/}}
\newcommand{\modname} {{\bf check\_map.tex}}		% file name in library
\newcommand{\modlibe} {{\bf read\_tools:$[$sogs$]$}}	% BROWSE directory

\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 Check Map 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}

% Abstract

The \checkmap tool scans a VMS link map for PSECT mismatches and
undefined symbols.

\clearpage				% Table of Contents page

\tableofcontents

\clearpage

\section{Introduction}

The \checkmap tool scans a VMS link map for PSECT mismatches and
undefined symbols and produces a short report on any of link map
problems.

A PSECT mismatch occurs when two modules do
not map to a common PSECT in the same manner.  
Each PSECT will have a starting base address and a fixed length.
Each module that accesses that PSECT should have the same 
base address and same length.  The PSECT name, modules that access it,
base addresses, and length information is all given in the 
link map;  however, no mismatch information is given.

Only PSECTs that have the OVERLAY (OVR) attribute are considered
by the \checkmap tool.  Certain PSECTs that may have the OVERLAY
attribute are ignored, such as the \$BLANK PSECT.

An undefined symbol can be found in the link map when one
or more modules reference a symbol that has not been defined
in any of the link objects.  These are linker warning messages that appear
in the map file.

\section{Report Parts}

This section describes the two major parts of a \checkmap report:
\begin{itemize}
\item	PSECT Mismatch Tables
\item	Undefined Symbols Table
\end{itemize}

A \checkmap report contains a one line header followed by at least
one PSECT Mismatch Table and/or a single Undefined Symbols Table.
\subsection{PSECT Mismatch Tables}

A PSECT mismatch table contains data on one PSECT that has at least one
mismatched module.  It lists, in tabular form:
\begin{enumerate}
\item	PSECT Name - name of mismatched PSECT.
\item   Module Names - names of all modules that access this PSECT.  Mismatched
modules have (*) next to their name and a * next to the mismatch culprit (i.e. the
base address is off or the length is off).
\item Base Addresses - for PSECT and all modules.
\item PSECT Length - for PSECT and all modules accessing it.
\item Module File Name - to map a module to an object file.  A common cause of 
PSECT mismatch errors is linking obsolete object files with current object files.
\end{enumerate}
\subsection{Undefined Symbols Table}
The Undefined Symbols section is a brief table that lists:
\begin{enumerate}
\item	Undefined Symbol Name - name of referenced but undefined symbol (data or function or procedure).
\item   Module Lists - list of all modules that use the undefined symbol.
\item   Module File Name - file names of all modules that use this undefined
symbol. 
\end{enumerate}

\section{Invoking the Check Map Tool}

Use the following command to invoke the \checkmap tool:
\bigskip
\begin{verbatim}
   $ CHKMAP   <Map-file>  
              [<Output-report-file>]   
              [/EXC*LUDE=<Exclude-file -or- Exclude-list>]
              [/NOL*OG]
\end{verbatim}
\bigskip

$<$Map-file$>$ is the name of a VMS link MAP file.  Wildcards are allowed.
A default extension of ``.MAP'' is assumed if no extension is given.
{\sl Any.map, disk\$bruno:[b192.oss.exe]*.map;, 
disk\$bruno:[b192.ss.exe]rafstr.map \/}
are all examples of the Map-file parameter.

$<$Output-report-file$>$ is the name of the \checkmap output report file.  This is an optional
parameter.  If it is ommitted, the map file name (without directory specification) is concatenated
with the ``.CKM'' extension.  A report file gets generated only if there are errors found in the
link map.  A common output report file name is {\sl sys\$output\/} or {\sl tt: \/}.

A optional qualfier can be placed on the command, the ``/EXCLUDE'' qualifier.
With this qualifier, you can tell the \checkmap tool to ignore certain PSECT
names that have known mismatches in order to make the output report shorter.
The \checkmap tool can ignore known undefined symbols in the same manner.

An $<$Exclude-file$>$ is an ASCII file that contains one PSECT name or undefined symbol
per line starting in column one (comment lines begin with an ``!'' in this file).
This list is read in to form the exclude names list for the \checkmap tool.

The $<$Exclude-list$>$ is a list of one or more PSECT (and/or undefined symbol) names
seperated by commas, e.g. {\sl XSF, DANZA, CRPPRG \/}.

The ``/NOLOG'' qualifier will cause the \checkmap tool to not output success
messages.

\subsection{CHKMAP Command Symbol}

The CHKMAP symbol must be installed to execute a command procedure as follows:
\bigskip
\begin{verbatim}
       $ CHKMAP  :==  @devtools:ckmap
\end{verbatim}

in order for the above command description to function properly.  This 
command procedure sets up the call to the main \checkmap software as a foriegn
command and passes the correct parameters accoringly.

\subsection{Examples}

Some sample invocations follow:

{\small
\$ CHKMAP RAFSTR.MAP

\$ CHKMAP RAFSTR.MAP RAFSTR.CKM

\$ CHKMAP disk\$bruno:[b192.podps.exe]*.MAP sys\$output /EXCLUDE=exclude.list

\$ CHKMAP disk\$bruno:[b192.podps.exe]*.MAP sys\$output /EXCLUDE=XSF,DANZA,UNDEFSYM

\$ CHKMAP RAFSTR.MAP /EXCLUDE=XSF,DANZA,UNDEFSYM

}

\clearpage
\section{Sample Reports}

This section lists some sample \checkmap reports and follows each report with a summary:

\subsection{Sample Report 1}

{\tt\footnotesize
 \begin{verbatim}

----------   C H E C K - M A P   R E P O R T   F O R :  DISK$BRUNO:[B192.SS.EXE]RAFRCV.MAP;2   ------------


Psect Name        Module Name             Base Address        Length      File
----------        ------------------      ------------        --------    ------------------------------
RCV_FILE_TABLES                           0048253C            664         
              (*) RAFRABORT               0048253C           *592         [CUR.][SS.OBJECT]RAFRABORT.OBJ;2
              (*) RAFRCV                  0048253C           *592         [CUR.][SS.OBJECT]RAFRCV.OBJ;2
                  RAFRCLOSE               0048253C            664         [B192.][SS.OBJECT]RAFRCLOSE.OBJ;2
                  RAFRCREAT               0048253C            664         [B192.][SS.OBJECT]RAFRCREAT.OBJ;2
              (*) RAFROF                  0048253C           *592         [CUR.][SS.OBJECT]RAFROF.OBJ;2
                  RAFRWRITE               0048253C            664         [B192.][SS.OBJECT]RAFRWRITE.OBJ;2

 \end{verbatim}
}

This \checkmap report was generated using the command:
{\small
\begin{quote}
\$ CHKMAP DISK\$BRUNO:[B192.SS.EXE]RAFRCV.MAP
\end{quote}
}

This report shows:
\begin{enumerate}
\item There is one mismatched PSECT in this link map, namely: RCV\_FILE\_TABLES.
\item Three modules mismatch the length of this PSECT which is 664 bytes.
Each of these modules has a (*) next to their name, and a * next to the length
designating the PSECT mismatch occurred on the length not the base address.
\item All module filenames are printed next to each module in the PSECT
under the file column.
\item There are NO undefined symbols for this PSECT.
\end{enumerate}
\clearpage
\subsection{Sample Report 2}

{\tt\footnotesize
 \begin{verbatim}


----   C H E C K - M A P   R E P O R T   F O R :  DISK$BRUNO:[B192.PODPS.EXE]YP00IN.MAP;2   ----


Undefined             In
Symbol Name         Module                File
-----------         ------------          ---------------------------------------------
AMR_CEC_CEMMSQ      CP1PCM                DISK$TREX:[CUR.][PODPS.OBJECT]CP1PCM.OBJ;2
AMR_CPP_CP0MGP      CP1PCM                DISK$TREX:[CUR.][PODPS.OBJECT]CP1PCM.OBJ;2
MID_MCEFIL          CP1PCM                DISK$TREX:[CUR.][PODPS.OBJECT]CP1PCM.OBJ;2

 \end{verbatim}
}

This \checkmap report was generated using the command:
{\small
\begin{quote}
\$ CHKMAP disk\$bruno:[b192.podps.exe]yp00in.map
\end{quote}
}

This report shows:
\begin{enumerate}
\item There are no PSECT mismatch errors.
\item There are three undefined symbols all from the same module CP1CPM.
\item The undefined symbols table shows where the module CP1CPM can be found.
\end{enumerate}


\clearpage
\subsection{Sample Report 3}

{\tt\footnotesize
 \begin{verbatim}


----   C H E C K - M A P   R E P O R T   F O R :  DISK$BRUNO:[B192.PODPS.EXE]YP00IN.MAP;2   ----


Undefined             In
Symbol Name         Module                File
-----------         ------------          ---------------------------------------------
AMR_CEC_CEMMSQ      CP1PCM                DISK$TREX:[CUR.][PODPS.OBJECT]CP1PCM.OBJ;2
MID_MCEFIL          CP1PCM                DISK$TREX:[CUR.][PODPS.OBJECT]CP1PCM.OBJ;2

 \end{verbatim}
}

This \checkmap report was generated using the command:
{\small
\begin{quote}
\$ CHKMAP disk\$bruno:[b192.podps.exe]yp00in.map /EXCLUDE=AMR\_CPP\_CP0MGP      
\end{quote}
}

This report is exactly the same as the second sample reoprt with one
difference.  One of the undefined symbols was excluded from the report 
via the /EXCLUDE qualifier.

\clearpage
\section{About The Software}

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


\begin{enumerate}
\item {\it CHECK\_MAP.MMS \/}

This MMS file maintains the \checkmap software executable 
{\it CHECK\_MAP.EXE}.

\item {\it CKMAP.COM\/} 

This command file handles wildcards and certain command line checks before
calling the \checkmap software.

\item {\it CHECK\_MAP.SCN\/} 

This is the main program for this SCAN-based tool.  It parses the command
line to decide what options are present and calls routines to 
read in exclusion file (from /EXCLUDE qualifier) and to actually parse
the MAP file.  If the /EXCLUDE=$<$Exclude-list$>$ mechanism is used,
this SCAN module parses the list and adds the item to the exclusion TREE.
This software is called from {\it CKMAP.COM \/} as a foriegn
command.

\item {\it CMAP\_UTILS.C \/} 

This collection of C routines handles all of the output formatting of the
PSECT Mismatch and Undefined Symbol tables.  They are called from the SCAN
routines.

\item {\it HANDLE\_EXCLUDE\_FILE.SCN\/} 

This SCAN module reads in an exclusion file ignoring comment lines and storing
valid lines into the exclusion TREE.

\item {\it CMAP.SCN\/} 

This SCAN module does most of the work in the \checkmap software.  It is 
responsible for parsing through the MAP file ignoring irrelevant data and
picking up PSECT mismatches and undefined symbol data, and storing them for the report
later.  It calls all of the {\it CMAP\_UTILS \/} routines to handle the output
formatting.

\item {\it CMAP\_MESSAGE.MSG \/}

This file contains VMS-style error messages to be LIB\$SIGNALed or SYS\$PUTMSGed
to the user.

\end{enumerate}
\end{document}