\chapter{Using YAMP}
\index{YAMP }To a large extent the proceding discussion has been a
description of the header file \verb+ virt.h+.
\index{YAMP!virt.h}. The matrix programs consist of two
other modules \verb+ virt.cpp+ and \verb+ virtop.cpp+.
These two files need to be included in your Turbo C++
project definition. You also need to include virt.h in the 
module containing your main program. You also need to make
a global declaration of the dispatch matrix using
\begin{verbatim}
MStack *Dispatch = new MStack;
\end{verbatim}


You can start your program after this. See the file \verb+
test.cpp+ for my test suite of the YAMP modules. The vitual
memory model YAMP programs usually need the medium, large or
huge memory models.  It will also work in the small and compact
model if you strip the code that you do not need in
\verb+virtop.cpp+. You can also turn off the graphics 
functions to fit the virtual memory model into the small memory
model. There is more than 64k in the virtual memory text segment
as the system is configured now. The in-ram model will compile
into all but the tiny memory model.

\section{virt.h}
\verb+ virt.h+ includes several of the standard header
files. It then defines each of the objects and the
functions described in earlier chapters. These headers are
\begin{verbatim}
#include <d:dos.h>
#include <d:stdlib.h>
#include <d:stdio.h>
#include <d:math.h>
#include <d:string.h>
#include <d:io.h>
#include <d:fcntl.h>
#include <d:errno.h>
#include <d:types.h>
#include <d:stat.h>
#include <d:iostream.h>

#define STACKLENGTH 16352

#define NDECS 10
#define ZERO (1.0E-8)

\end{verbatim}
The disk 'd:' is where the headers are stored for
compilation. It is a RAM disk in extended memory.
Compilation is faster when reading headers from a RAM disk
even on 386 machine. The d drive is also where
\$\$\$\$vmem.tmp can be created. Recent versions of BC use
precompiled headers, so you might want to remove the d: from the
includes. 

The variable STACKLENGTH\index{YAMP!STACKLENGTH} is
defined. You can increase this as needed up to 64k bytes in
Turbo C++. This variable is not need for most programs
since the 4096K stacklength is sufficient.  You must turn
off stack checking and resort to the huge model to avoid
fixup overflow error messages\cite{BR:Cpp}. This can be a
dangerous thing to do in pointer intensive programs.
Use the following statement in your main module before
defining Dispatch to modify the stack length
\begin{verbatim}
unsigned int _stklen = STACKLENGTH;
\end{verbatim}
The best advice regarding the stack is to try
to limit the number of local matrices in any single
function. This keeps the stack within the default 4096k
bytes. Each local VMatrix takes 104 bytes off of the stack.

The variable NDECS is used in the conversions of strings to
floats in the data IO functions. The variable ZERO is used
in sweep and elementwise division. It can be reduced where needed.

\section{virt.cpp and virtop.cpp} 
The file \verb+ virt.cpp+\index{YAMP!virt.cpp} branches
according to the in-ram or virtual memory modules. These modules
contain the member functions, stack, and friend functions. The
correct memory model is selected depending on defining
\verb+IN_RAM+. The file \verb+
virtop.cpp+\index{YAMP!virtop.cpp} contains the matrix functions
discussed in the previous chapter. This is the file where you
can add your matrix functions. 

\section{Selecting a Memory Model}
The file \verb+ virt.cpp+ depends on defining the compiler
directive \verb+ IN_RAM+. If it is defined, then \verb+
VIRTRAM.CPP+ will be included for the in-ram memory system.  The
virtual memory version will be used by including \verb+
VIRTDISK.CPP+ if \verb+ IN_RAM + is not defined. Both of these
files must be in the include path definition of your project, or
BC cannot find them. The matrix operation file, \verb+
VIRTOP.CPP+ works the same way for both memory models.

\section{Selecting Graphics}
Including graphics depends on defining the compiler directive
\verb+VERTGRAF+\index{GMatrix!VIRTGRAF}. If it is defined then
\verb+VIRT.H+ will include the graphics prototypes. You must
also add \verb+VIRTGRAF.CPP+ to your project definition or make
files. 


\section{Using An Environment Variable}
You can redirect where \$\$\$\$vmem.tmp is created by
defining a DOS environment
variable\index{YAMP!TMP}\index{TMP environment variable}.
Use the statement
\begin{verbatim}
set TMP=D:
\end{verbatim}
before running a program that uses the virtual memory
system. This command assumes that you have a RAM disk named
D:. Consult your DOS manual for how to configure your
system with a RAM disk. If you don't have more than 1 meg
of ram, then you won't benifit from using a RAM disk for
the vmm system. The vmm system creates large matrices,
which will not fit will into small RAM disks. Instead, you
should use your hard drive. This can be really slow though.
You must decide to make the tradeoff between size and speed.

\section{Making a LIB}
YAMP has a lot of code that goes unused in many programs. One of
the ways to eliminate this code from your executables is to
build a LIB. The link step only pulls in code from the library
that has been called by the program. I have included a make file
that builds the library using Borland's make and C++ compiler.
You can fiddle with it to build your own library. Make sure to
modify the directory names to conform to your system. I have
also included a make file to build the three test files found in
the appendices. Issue the instructions

\begin{verbatim}
  make -fto_lib.mak 
  make -fmaketest.mak
\end{verbatim}

\noindent to make the library and test files. These will produce files
that use floating point emulation, and default Borland
optimizations. The library will not include debug information
and the test files will include it. I had some trouble creating
the libraries using the speed optimizations. The test files
produce garbage even though they link without errors. This may
have happened because I was trying to exclude debug info in the
lib but not in the exe's.

\section{Using YAMP under Windows}
There are still some open problems in YAMP for making it work
under WINDOWS. I have tested it under the Borland 3.0 Windows
C++ compiler, and in a standard dos exe under a Windows DOS
session. Text based programs compile, link, and run just fine.
The GMatrix functions will not be accessable in a Windows exe
since some of the BGI functions are not available under Windows.

Only one program can currently be running that uses the YAMP
virtual memory model. If you try to multitask two YAMP programs
you will get file sharing errors on \$\$\$\$vmem.tmp I
considered trying to fix this, but balked because it would embed
a lot of machine specific code in what appears to be a portable
program. If you want to run more than one YAMP virtual program,
you must alter the routine \verb+vopen()+ in
\verb+VIRTDISK.CPP+. You must make it detect file sharing
errors, or the presence of another .tmp file. It should also
detect the presence of Windows from within a dos or Windows
session. Then you must change the name construction section to
open another \$\$\$\$vmem.tmp, say \$\$\$\$vmem.tm1.