\section{First steps}

\subsection{Starting}
It is possible to run \szadb\ either from a desktop or from a text shell, in
either low, medium or high resolution. In this tutorial we will assume that
\szadb\ was launched from a command line on a screen 80 characters wide (this
setting affects only the layout of some displays) and that the executable is
called \adb, in tribute to its older brother.

The simplest way of starting \szadb\ is to type something similar to
\begin{exmpl}
	\adb\ {\it program.ext}
\end{exmpl}
where {\it program.ext} is any executable.
Note that the file extension (\name{tos}, \name{ttp},\name{prg})
must be provided.
For debugging purposes, it is preferable to compile your
program with debugger information (symbol tables). For Sozobon pass the option
\name{-t} to either \name{cc} or \name{ld}.
It is possible to debug a program without this
information but this is not a trivial task. This tutorial assumes that symbolic
information is provided.

For debugging purposes, it is much preferable not to strip off symbol
tables.  In this tutorial we will always assume that this was not
done.
To achieve that effect, while compiling 
with Sozobon C, pass \name{-t} flag to \name{cc}.

If you do not have your favourite test program handy then
you may compile from the provided sources
and use for experiments a simplified version of \name{unexpand.tos};
it replaces, if possible, runs of white space 
from stdin with tabs and writes results on stdout.
Further examples will use that program compiled by Sozobon C compiler,
version $1.2$, with \name{-t} and \name{-O} flags.

Once the debugger is started you should see on your screen a display
resembling the following:
\begin{exmpl}
	{\tt Szadb version 2.1mj(english)}\\
	{\tt >} 
\end{exmpl}
indicating that everything is in order.
The character {\tt >} is the prompt.  Its presence is the most striking
visual feature showing that we are not dealing with the ``real''
\name{adb}.

\subsection{Where am I?}
If you hit at this moment \key{Return} key \szadb\ should respond
with
\begin{exmpl}
	\verb|__start:|
\end{exmpl}
The debugger positioned itself at the very beginning of a loaded program.
\szadb\ ``remebers'' the last command and its current location, which
is known as ``dot''.  You may set ``dot'' by typing any valid expression
which will evaluate to an address. Hitting \key{Return} by itself repeats
the last typed in command (not the executed one! This distinction will
be important later).

In this version the ``dot'' is set to low TPA, or a starting execution address.
The initial default command is \name{/a}
which will print the symbolic value of ``dot'' followed by a colon.
To see a numerical display of the ``dot'' try the following:
\begin{exmpl}
	{\tt .=X \key{Return}}
\end{exmpl}
for a hexadecimal address, or
\begin{exmpl}
	{\tt .=D \key{Return}}
\end{exmpl}
for the same one in a decimal form.

A note for {\sc Unix} hackers. In \szadb\ there is no distinction
{\it objectspace} and {\it dataspace}.
Therefore prefixes \name{?} and \name{/} in commands are equivalent.
Typing \name{?a} will cause the same effect as typing \name{/a}.

Addresses are printed in a form \name{symbol+offset}, where possible.
If there is no symbol table, or if \name{offset} is getting too big,
you will notice that addresses are printed as hexadecimal values.
The offset limit has initialy value of 0x400 but it can be changed by
\verb|$s| request, in the form 
\begin{exmpl}
	\verb|$s <new_value>|
\end{exmpl}
The default number base for commands and displays is sixteen (hexadecimal).
Please refer to the documentation on how to change the default base and use
numbers in other bases.

White space, which is not a part of a literal string, is not significant
in \szadb\ requests as long as a total number of characters in the command
line is below an input buffer length (78 for this version).  \key{Return}
always terminates a current line.
Try adding some blanks and tabs to previously typed commands.

\subsection{Disassembling}
Lets try something more exciting.  A request for printing machine
language instructons is \name{/i}.  It may be preceded by a count.
Try \name{,4/i}.  The comma is necessary and informs \szadb\
that what follows is a number of times to repeat the request.
If you will omit it then the debugger will decide that 
you want to start with a location 4.
If all is well then \szadb\ will respond
\readexample{firstdis.exm}
After this request a default command becomes \name{/i}.  Therefore to see
the next four locations it is enough to type \name{,4} and \szadb\
will show
\readexample{reptdis.exm}
\par
Note that the ``dot'' has moved.  This is a common feature of all memory 
examining requests. The  ``dot'' will be set past all already scanned
memory.  If you want to look at the same memory area one more time,
possibly using a different request,
use \name{\&} to reset your position.
It is a shorthand for the last {\em typed in\/} address.

\subsection{More on talking to \szadb}
A general \szadb\ command has a form
\begin{exmpl}
	{\it address ,count request\_with\_its\_modifiers}
\end{exmpl}
where each of three parts is optional or possibly not used.
Please refer to the documentation to see all available requests.
For all practical purposes count $-1$ means forever.
Read a little bit further before trying this.

Display format modifiers can be concatenated together. For example,
the following
\begin{exmpl}
	{\tt main,9/ai}
\end{exmpl}
will print the first nine instructions,
labelled by their addresses, starting from \verb|_main|. Like this:
\readexample{maindis.exm}
Note that the leading underscore, required to produce an internal form of
a symbol \name{main} was prepended automatically.  To get to an
address of \verb|__main|, if such symbol in your program exists,
you have to type its name in full.  Similar but slightly different
rules will be in force if your program has a symbol table
in the MWC format.

If you do not know which symbols are available issue a request \verb|$e|.
A display similar to the following will start to scroll accross your screen.
\readexample{symbols.exm}
The general method to stop a scrolling screen
for a moment is to use \key{\carret S} and any other key will
continue.  A \key{\carret C} will cancel the command and any further
output. Starting with version 1.4 this includes also a paging.  This
means that display stops after showing one screenful of symbols and
\szadb\ waits for your keyboard input.  Keys \key{q}, \key{Q} and
\key{\carret C} break, any other key continues.  A processing of 
the request is finished when you will get back
a standard \szadb\ prompt of ``>~''.

Some hexadecimal numbers may look like symbols.  For example, if you
happen to have a symbol \name{abba} in your program then \szadb\
will understand \name{main+abba} as a request for setting the ``dot''
to an address which is a sum of addresses of \name{main} and \name{abba},
even if you really meant an adress at offset of \name{0xabba} from
\name{main}.  To avoid this misinterpretation it is enough to type
\name{main+0abba} --- a number has a leading zero.
It the symbol \name{abba} is not defined then the ambiguity does not arise.
Assuming that the default base is sixteen \name{abba} will be taken
as a number. 
Otherwise such expression will be not accepted and you will see
only an error message.
The form \name{0xabba} has a unique meaning and always works.
