\section{Running under \szadb}

\subsection{How to run --- with arguments}
To run a loaded program, with a name passed as a \szadb\ argument,
one has to type \name{:c}, which is a short for \name{:continue}.
When the program is running \szadb\ switches to the program screen which
is different from that one used by the debugger.
In particular, all program keyboard input will be accepted from the program
screen.  Unfortunately there is no way, at least not in this version,
to read the debugged program standard input from a file.  It has to
be typed in.
To switch from the \szadb\ screen the program window use \key{\carret W}
and return from the visit with any other character.

The program itself may have arguments.  In principle there are
two methods with which they can be set.
Firstly, you may specify them when starting \szadb.
Everything which
follows the name of a loaded executable will be taken as its arguments
and copied verbatim to its basepage. A request \verb|$p| will display the
whole basepage and it will allow you to check if you really got what
you expected.
\szadb\ does not allow for any argument extending schemes
and it will trunctate command lines which are too long.

The second method allows you to specify arguments as an optional tail
of \name{:c} request.  Once arguments were set, by any of these methods,
they cannot be changed and further attempts to do so will be ignored.

Since both shell command lines and 
the input line inside of \szadb\ are limited in length,
and partially already taken,
it may appear that there is no way to fill all available basepage
space with program arguments by any method,
short of writing directly to a computer memory.
As we will see later this is not true, even if 
it requires a little bit of trickery.
(See further descriptions how to define and execute function keys.)

When you are ready to quit, because you are done or lost and wish to start
afresh, enter \verb|$q|. If the debugee process exited of its own accord
then \szadb\ will terminate too.

\subsection{Setting breakpoints}
Executing a program under a debugger is of no great use without breakpoints.
Here is the simplest way in which they can be set.
\begin{exmpl}
	{\tt main:b}
\end{exmpl}
We can do even better than that. Try
\begin{exmpl}
	{\tt main:b ="My first szadb breakpoint"n;.=XD;,8/ai}
\end{exmpl}
Everything which follows \name{:b} on the input line will be stored and
executed later on when the breakpoint is hit.
Multiple commands are separated by semicolons.
By the way, you may use semi-colons for immediate requests too.

Breakpoints also can have counts.  Using as an example \name{unexpand.tos},
and a fragment of its disassembled code shown in a previous section, we 
may set a breakpoint
\begin{exmpl}
	{\tt main+18,3:b="about to read"n}
\end{exmpl}
in a main loop of this program, just before {\tt fgetc()} is called.
With this count an execution will stop only 
for every third character to be accepted.

Setting a breakpoint on the top of an existing one is allowed and it will
simply cause a replacement --- changing possibly a count and
commands to execute.  A list of all current breakpoints, with their counts
and associated commands,  is produced by the \verb|$b| request.
Information shown at the bottom of this list will be explained later.

It is not the best idea to set a breakpoint somewhere between two program
instructions.  Nothing terrible will happen immediately,
but your debugging run may end up prematurely amid an utter confusion.
Sometimes it is possible to
restart a wayward program by writing a needed address directly into a
program counter with a {\it address}{\tt >pc} request, but this is not
guaranteed to work.  It is also advisable to keep breakpoints on an
execution path.  They are a limited resource and there is no point
wasting it.

\subsection{Displaying information}
\szadb\ provides many ways to display information about the state
of your program.  Some of these requests were detailed above. Another
is \verb|$r|, which will show the contents of all registers
and status flags. If you are interested
in an individual register then use something like
\begin{exmpl}
	{\tt <a0=X}
\end{exmpl}
Replacing above {\tt =}
with {\tt /}, or {\tt ?}, will bring a hexadecimal display of the long
word stored at the location pointed to by register {\tt a0}.
Careful here, the last form will move the ``dot''.
There are many other possible formats.
Try, for example, \hbox{{\tt main,20/x}} and \hbox{{\tt <b,2/s}}.

The second example uses one of four read-only variables provided by
\szadb, which are
\begin{exmpl}
	\makebox[.70in][l]{\tt l}lowest text address\\
	\makebox[.70in][l]{\tt t}length of the text segment\\
	\makebox[.70in][l]{\tt b}start of the bbs segment\\
	\makebox[.70in][l]{\tt d}length of the data segment
\end{exmpl}
With an exception of {\tt l} names follow the {\sc Unix} convention.
They will be particulary handy if you will have 
a misfortune of debugging executable without a symbol table.

Formats in requests can be combined.  Let us try something like
follows.
\begin{quote}
   {\tt ="Text memory dump"2n;main,<b-main\%8+1/4x4\carret rr|rr8cn}
\end{quote}
and here are initial lines of a resulting display, where ``.''
replaces all non-printable characters.
\readexample{dump.exm}
Note that division is denoted by a \verb|%| character and that 8
divides a difference \verb|<b-main| and not only \verb|main|,
since all expressions are evaluated in strict left-to-right order.

Let's break down the format modifiers to see what is actually happening
\begin{exmpl}
  \makebox[.70in][l]{\tt 4x} print four short words in hex,\\
  \makebox[.70in][l]{\tt 4\carret} backup the ``dot'' by four
	current fields (short words),\\
  \makebox[.70in][l]{\tt rr|rr} print 2 blanks, 
       vertical bar, and 2 more blanks,\\
  \makebox[.70in][l]{\tt 8c} print 8 characters,\\
  \makebox[.70in][l]{\tt n} and a newline.
\end{exmpl}

Displays that are wider then a current screen width (40 or 80) will
have lines split automatically.

\subsection{Recording your session}
A request \verb|$>|{\sl filename\/} starts writing a transcript 
of everything which shows
on your screen to the file {\sl filename}. All examples longer than a couple of
lines were prepared this way. If the {\sl filename\/}
is missing then the currently
opened transcript will be closed. The output is always appended to the given
file, so that it is possible to open, close, and re-open the same file any
number of times.

Because GEMDOS is not re-entrant it is not a very
very good idea to perform an actual file write while processing
a GEMDOS call.
It is nearly certain you will crash your system.
The safest course in such spots is to turn recording temporarily off.
However, transcript output is buffered by default, so actual
writes occur only when the buffer is flushed when full or because the file was
closed. Therefore with proper care, one can empty the buffer prior to
dangerous spots and even create a record of a GEMDOS call, provided it is not
too wordy. A handy definition for a function key to do this is 
\hbox{\verb|$>;$>|} (see the last section on function keys).

It is advisable not to write files to your hard drive, instead use a RAM drive
or a dedicated floppy (which can be reformatted in case of disaster). Remember
that a buggy program and the debugger can write anywhere. Over system file
buffers and cached File Allocation Tables as well.

If you need all memory you can get it is possible to turn off
transcript buffering with command line option {\tt -nb}.  But then
you will have to be extremely careful about possible conflicts with
GEMDOS.

{\sc Note!}  After \verb|$>|{\it file\/} request your default command
is \verb|$>| and not the last command you were executing previously.
It is possible to execute \verb|$>| inadvertently by hitting \key{Return}
or by making some mistake while typing the next line.  This will close
your transcript with obvious results.  When something like thats
happens, or when in doubt, issue another \verb|$>|{\it file\/}.
