%%%%%%%%%%%%%%%%%%%%%%%
%   szadb primer      %
%   version 2.1       %
%   August, 1990      %
%   updated - May 1991%
%            July 1991%
%         January 1992%
%%%%%%%%%%%%%%%%%%%%%%%
\documentstyle[twoside,11pt,verblist]{article}

\title{\protect{\LARGE{\tt szadb} {\bf primer}}}
\author{Micha{\l} Jaegermann \\[.6in]
	edited by\\
	Anthony Howe}
\date{14 Jan 1992}

%%
\newcommand{\szadb}{{\tt szadb}}
\newcommand{\adb}{{\tt adb.ttp}}
\newcommand{\name}[1]{{\tt #1}}
\newcommand{\key}[1]{{\sf $\langle$#1$\rangle$}}
\newcommand{\carret}{\char94}
\newlength{\exmpskip}
\setlength{\exmpskip}{2\parindent}
\newenvironment{exmpl}
  {\begin{quote}\setlength{\leftskip}{\parindent}}{\end{quote}}
\newcommand{\readexample}[1]
   {\medskip\inputverbatim[\exmpskip]{#1}\medskip\noindent}
%%
\begin{document}
\vfill
\maketitle
\thispagestyle{empty}
%%
\titlepage\null\vfill{\sf 
\begin{quote}
	There is NO WARRANTY with respect to this publication, or the
	program it describes, and disclaim any implied or explicit
	suggestions of usefulness for any particular purpose.  Use
	this program only if you are willing to assume all risks, and
	damages, if any, arising as a result, even if caused by
	negligence or other fault.

\bigskip
	Sozobon C compiler and \szadb\ debugger are both copyright
	\copyright 1989, 1992 by Sozobon Ltd.  Both can be freely copied
	and distributed provided all copyright notices will remain
	intact and all modified versions will be clearly marked as such.

\medskip
	Atari, ST, TOS and GEMDOS are trademarks of Atari Co.\\
	GEM is a trademark of Digital Research Co.\\
	Mark Williams C is a trademark or Mark Williams Co.\\
	{\sc Unix} is a trademark of AT\&T.
\end{quote}
}\par\null\endtitlepage
\sloppy
%{\tt  % turn this on if you want to make life easy for dvi2tty
%\raggedright  % and this..
%\raggedbottom % and this as well
\section{Introduction}

\szadb\ is an assembly level debugger for programs written for the TOS 
operating system on the Atari ST computer.
It is primarily meant to be a companion
to the freely distributed Sozobon C compiler, and can be copied and passed
around under the same conditions.

One of design goals of the original \szadb\ project was to provide 
a debugger closely resembling {\tt adb},
which is available on most {\sc Unix} systems. There are some dissimilarities
which follow mostly from differences in target machines
and operating systems. Still users with an {\tt adb} experience should feel
right at home.

The originally released version 1.0 was written by Johann Ruegg and Don Dugger.
Expanded to version 1.2 in a joint effort of Anthony Howe and Michal{\l}
Jaegermann.  Further development to version 1.4 by Michal{\l} Jaegermann.
A document describing version 1.2 was prepared by Anthony Howe and
Micha{\l} Jaegermann.  Modified slightly by the last author to reflect
changes in versions 1.3, 1.4 and 2.1

This manual does not describe versions of \szadb\ as they were
released as parts of Sozobon~C compiler packages, but rather modified
relatives which are not products of Sozobon team and which provide
richer and more flexible user interface for a price of an increased
demand on computer resources.

Version 1.2 introduced multi-command input lines,
which could be attached to breakpoints and stepping commands.
Other it features included recording of 
a debugging sesion in a file, definitions 
function keys, and other assorted niceties.
In addition to original Sozobon C symbols
(Alcyon C style, also a default for ST version of gcc compiler)
it also accepted the symbol table formats from Mark Williams C.

Version 1.3, not very widely distributed, added to this list
a ``GST extension'' of a symbol table format, with
symbols up to twenty two characters long.
Executables with such tables are produced by
newer versions of gcc (ST) loader with \name{-G} option to the
compiler.

Version 1.4 expanded a range of supported screen displays.
In particular it is possible now to run \szadb\ in all six TT resolutions.
Moniterm, in a tandem with a standard ST monitor, also can be used
in a particularly convenient manner.  If you have some graphic
card which disallows switching of a screen base check if Moniterm
remarks will not apply to your situation.

Version 2.1 added a support for ``SozobonX'' symbol table
format which showed up in version 2.0 of Sozobon~C compiler.

If your compiler's symbol table format is not supported, or there are 
other changes
or additions you wish to add, the complete source is provided free
with the debugger.  For symbol tables check file \name{adb1.c},
a function \name{setsym()} and a family.

The document you are reading now serves as a gentle introduction to 
``adb way of debugging''.  It gives expanded explanations and
examples but it does not cover all points described
in a formal szadb description.  Read the other document in any case!

\input{firsteps}
\input{running}
\input{debug}
\input{topics}
\clearpage
\pagenumbering{roman}
\tableofcontents
%}   % turn this on if you want to make life easy for dvi2tty
\end{document}
