\chapter{Customizing the software}\label{custom}  % -*- Mode:TeX -*-

A number of features of the \cam\ Forth system may be personalized\index{Software/customization}
according to your taste, your needs, and your resources.   These changes
can be made on the fly, from the Forth interpreter, and forgotten at the
end of the session; they can be retained from session to session, by
saving the customized version of the system to disk; or they or can be given a
permanent status in the software by entering them in the appropriate source files and
recompiling the relevant part of the system.

\section{Personalized features}\label{personalize}

The following considerations apply indifferently to \id|F83.EXE| or
\id|CAM.EXE|---which is a superset of the latter; we'll use {\tt CAM} in
the examples.

\bigskip

Fire up \id|CAM.EXE| from DOS, as in Section \ref{startup}.  You'll
recall that the screen editor places a stamp with user identification
and date\index{Editor/date stamp} on each screen you create or modify (Section
\ref{stamp}).  To tell \id|CAM| who you are, type
        \begin{verbatim}
    I'M xyz\end{verbatim}
where \iprog{I'M} is a Forth word that enters \id|xyz| (or
any other three-letter choice) as your identifier.

If your \pc\ system has no clock, it is a good idea to include the
DOS \id|DATE| and \id|TIME| commands in the \id|AUTOEXEC.BAT|
file (which is executed whenever the \pc\ is booted) to encourage
you to enter the current date.

\medskip

The default base\index{Forth/number base} for numeric conversion (when you
type in numbers directly to the Forth interpreter, or when you want it
to print out numbers) is ten.  If you prefer base sixteen, type
        \begin{verbatim}
    ' HEX IS SET-BASE\end{verbatim}
        As usual in Forth, you can change to any base at any time,
depending on the current needs; the base you choose with
\iprog{SET-BASE} is that which is selected by default whenever you enter
the interpreter, and restored when an error occurs, you hit the
\keybreak\ key, or load a file (with \keyl\ or \keyL) from the \cp.

\medskip

The default choice is that upper- and lower-case names are distinct
(and some existing Forth words of no concern to you make use of this
distinction).  If you wish to be able to type upper- and lower-case
interchangeably (which we, however, discourage), give the command\index{CAPS ON{\tt CAPS ON}}
        \begin{verbatim}
    CAPS ON\end{verbatim}
        and everything you type thereafter
will be read as upper-case.

\medskip

If you are using separate monitors for \cam\ and the \pc, type
\id|2 DISPLAYS|\index{DISPLAYS{\tt DISPLAYS}}\index{Display/mode} to prevent the software from trying to share
the \cam\ monitor with the \pc\ (Appendix \ref{monitor}).\index{Monitor/configuration}

If you have a Centronix-like---rather than Epson-like---printer\index{Printer}
(for other printers see Section \ref{custom-screens}), type
        \begin{verbatim}
    ' CENTRONICS IS INIT-PR\end{verbatim}

\medskip

Section \ref{hard} discusses how to change the defaults for where the
system expects the source files to be.\index{File/source} Section
\ref{editing} mentions the {\sc variable} \iprog{AUTO-X}, whose default
value you may want to change.  Similarly for the {\sc variable}
\iprog{INS0}, which controls whether you are in insert mode when you enter
the screen editor.\index{Editor/insert mode}.

\bigskip

If you have made any of these changes, you can save your customized
version\index{Save modified system} of \id|CAM| just by typing\index{SAVE-SYSTEM{\tt SAVE-SYSTEM}}
        \begin{verbatim}
    SAVE-SYSTEM C:CAM.EXE\end{verbatim}
        or whatever name and drive you choose.
Provided you keep a copy of the original
\id|CAM.EXE| (or \id|F83.EXE|, if that's what you are customizing), no
irreversible damage can be done if you somehow mangle this process.

For documentation and repeatability, the above operations or any number
of other minor changes or additions can of course be edited first on a
screen, and then loaded into the system (cf.\ Section
\ref{custom-screens}).  

\section{Recompiling the {\tt CAM} system}\label{meta}

If you want to extend or improve \cam\ Forth you
are provided with all the information and the tools to do it.\index{Software/system generation}

Starting from Forth's {\sl kernel\/}\index{Forth/kernel}\footnote
        {This is a minimal, executable Forth system containing just
enough resources to be able to bootstrap itself by compilation
of additional Forth screens.}
        you can regenerate the whole \id|CAM| system from scratch---after having
made any desired changes in the appropriate source files.  For less extensive
changes, you may want to start your regeneration process at a later
stage.  On the other hand, if you really want you can start at an even earlier
stage: using the current version of Forth and the provided metacompiler
you can generate a new kernel---one that speaks a somewhat
different dialect of Forth, or perhaps a radically different one.

\subsection{Generating a new {\tt CAM.EXE}}\label{gene-cam}

If you only want to change something in the {\tt CAM} portion of the
source code (files of the form \id|CAM-*.4TH|) you only need to
recompile this part of the system.

With all of the \id|CAM-*.4TH| files on the default drive, in the
default directory (here we'll use \id|C:|) start up the \iprog{F83.EXE}
program from DOS by typing
\begin{verbatim}
    C>f83 cam-load.4th\end{verbatim}
        (of course, you could give a path-name for \id|F83.EXE|),
and once you are in Forth type \id|OK|.

This loads all of the required files, and (if everything runs without
errors) creates a new version of \iprog{CAM.EXE}.  If one of your changes
causes an error during loading, you will be placed in the editor at the
point that needs to be corrected;  once you are ready to try again, exit
to DOS and begin anew.


\subsection{Generating a new {\tt F83.EXE}}\label{gene-f83}

If you have made any changes in the files \iprog{EXTEND86.4TH},
\iprog{CPU8086.4TH}, \iprog{UTILITY.4TH} or \iprog{PC.4TH}, to regenerate the
\cam\ system you must first generate a new \iprog{F83.EXE} and then
follow the procedure of the preceeding section.  

If you already have the program \iprog{KERNEL.EXE} in your files you can generate \id|F83|
directly, otherwise you will have to run a meta-compilation first (see next
section) to generate \iprog{KERNEL.EXE}.

With the four source files mentioned above all on the default drive,
in the default directory (say \id|C:|) start \id|KERNEL| from DOS
with
        \begin{verbatim}
  C>kernel extend86.4th\end{verbatim} 
        and once you are in Forth type
\id|OK|.  This loads all extensions and creates a new version of
\id|F83.EXE| on the default drive.

Say \id|BYE| to Forth, and you're done and back in DOS.  Note that if you get any
compilation errors before about the middle of the file \id|PC.4TH|
there won't yet be a screen editor loaded, and so Forth will only be
able to print out the file, screen number, and line number where the
error was detected---you'll have to exit to DOS and start up a working
\id|F83| or \id|CAM| to make corrections. 


\subsection{Generating a new {\tt KERNEL.EXE}}

\index{Forth/kernel}If you want to change something in the file \iprog{KERNEL86.4TH}
(which defines Forth ``in Forth'' for the metacompiler\index{Forth/metacompiler}), you
will have to go through all three stages of the compilation process in order to
get a new working \id|CAM| system; this only takes a few
minutes.

Make sure \iprog{META86.4TH} and \iprog{KERNEL86.4TH} are on the default
drive (again, we'll use \id|C:|) and start up either \id|F83| or
\id|CAM| (the metacompiler can be run from either of these).  Type
        \begin{verbatim}
    C>f83 meta86.4th\end{verbatim}
        (or \id|cam meta86.4th| if you're starting from 
\id|CAM.EXE|).  Once you are in Forth, type \prog{OK} and
the meta-compilation will begin.  When it is done, say \id|BYE|
to leave Forth.  You now have a new \id|KERNEL.EXE| file,
and can proceed to produce the rest of the system.

\subsection{Custom screens}\label{custom-screens}

If you are recompiling \id|F83|, you may first want to customize
certain default parameters by editing the appropriate source screens
(the most relevant options are on screen 13 of \iprog{EXTEND86.4TH}),
so that the changes will be permanently incorporated in the software.\index{Software/custom screens}  For example, you
might want to define your own version of \id|NORMAL|,
        \begin{verbatim}
                                     : (MY-NORMAL)
                 (NORMAL) REVERSE ON ;
    ' (MY-NORMAL) IS NORMAL\end{verbatim}
        which would have you normally work in reverse video (black characters on a
white background).

\medskip

To produce pleasing listings with a printer different from the default
one (Epson-like), you should find out how to put your printer in
compressed mode.  If your printer\index{Printer} is a Centronics, for example, you
should comment out the command
        \begin{verbatim}
    ' EPSON IS INIT-PR\end{verbatim}
        on screen 13, and activate the (normally commented-out) command
        \begin{verbatim}
    ' CENTRONICS IS INIT-PR\end{verbatim}
        on the same screen (the appropriate \id|CENTRONICS| word
is already defined in the system).

If your printer is something else, you will need to define a word to set
it up.  Suppose your printer is a Kludge-97 and wants to receive a
{\sc control}-C character to put it in compressed mode; then you should say
        \begin{verbatim}
                                     : KLUDGE-97
                      CONTROL C EMIT ;
    ' KLUDGE-97 IS INIT-PR\end{verbatim}
        Even if you don't want to recompile the system at this moment, you can edit screen
13 of \id|EXTEND86.4TH|, load just this screen by hand (using \id|LOAD|), and type 
        \begin{verbatim}
    SAVE-SYSTEM CAM.EXE\end{verbatim}
        This gives you an executable version of \id|CAM| in which
\id|INIT-PR| is vectored to \id|KLUDGE-97|; moreover, since the screen
already has the desired changes in it, if you ever recompile the system
you won't have to redo these changes---they'll be automatically
incorporated.


\section{Installing the system on a hard disk}\label{hard}

If you have a hard disk,\index{Hard disk} it is desirable to transfer to it all of the
\cam\ software (or at least the files with extension \id|EXE| and \id|4TH|).

Make a new directory in the hard disk---{\tt CAM} is as good a name as
any for this directory---and copy to it all the distribution
software:
        \begin{verbatim} 
    C>CD \
    C>MD CAM 
    C>CD CAM 
    C>COPY A:*.*/V\end{verbatim}
        (we assume the hard disk is drive \id|C:| and the floppies
use \id|A:|). The last line will have to be repeated after inserting
each floppy.

\medskip

To run \id|CAM|, boot the computer in the usual way,
go to directory \id|CAM| in drive \id|C:|, and type \id|CAM|.

\medskip

If you have a hard disk (or large-capacity floppy-disk drive) and have
moved all of the sources to one drive, you should tell the \iprog{VIEW}
facility (Section \ref{view}) where to find the source files.\footnote
    {As supplied, {\tt VIEW} and {\tt FIX} will look for the sources on the
{\sl default} drive.}
    Assuming
the hard disk is in drive \id|C:|, type
        \begin{verbatim}
    DRIVE C: IS-HOME-OF KERNEL86.4TH
    DRIVE C: IS-HOME-OF EXTEND86.4TH
    DRIVE C: IS-HOME-OF CPU8086.4TH
    DRIVE C: IS-HOME-OF UTILITY.4TH
    DRIVE C: IS-HOME-OF PC.4TH\end{verbatim}
        for the \id|F83| sources, and similarly for the \id|CAM| sources.
In general, if you are keeping the source code on-line but have moved
some of the files from the drive where the system expects it to be to
another drive, you'll have to do something similar.\footnote
        {Eventually, this
problem will be solved more satisfactorily with a variant of the DOS
\id|PATH| command, which will let you specify the paths to be searched
when source code is being sought; for the moment, directory paths are
not supported from within Forth.}
        However, information about where each source file resides is
automatically updated if you re-generate the system (cf.\ Section
\ref{meta}).  

If you are using DOS version 3.0 (or later), you can put the source files
in a separate directory, and give that directory a drive letter using the
\id|SUBST| command.


\section{Mouse}\label{mouse}

\index{Mouse}When using the plane editor, some of the keyboard functions can be
complemented by a mouse used as a pointing device (Section \ref{dot}).  For this purpose,
\cam\ Forth supports a {\sc mouse systems} mouse, plugged into serial
port 1. No software installation for the mouse is needed.

The mouse connects to serial port 1 (device COM1), and uses interrupt no.\ 4.
There are no provisions for setting it up as COM2; on the other hand, the mouse
interrupt number can be changed (should there be an interrupt-number conflict with other
hardware sitting on the \pc\ bus) by writing the desired value in the {\sc variable}
\id|MOUSE-IRQ#| (see Glossary).

In later versions of the software we may allow a variety of mice by
having a separately installable mouse driver.  Check the file
\prog{READ-ME.DOC} for the latest information.