\chapter{The programming environment}\label{progenv}  % -*- Mode:TeX -*-

How does the \cp\ actually control the operation of \cam? 

The \cam\ module is plugged into the \pc\ {\sl bus}---a set of
address, data, and control lines which are managed by the microprocessor
contained inside the \pc.  To make \cam\ perform a certain activity one
has to instruct the microprocessor to conduct a certain dialog with
\cam\ via this bus.

To make a long story short, the \prog{CAM.EXE} program which you execute when
you want to run \cam\ consists of a number of program modules that have
been written by somebody who knows \cam\ and the \pc\ intimately, and of
a main ``dispatcher'' program which continuously monitors the keyboard.
Whenever, say, the \keys\ key is hit, the dispatcher summons the program
module in charge of telling \cam\ how to perform a step; when you hit
\keyG, the dispatcher summons the module in charge of loading a
configuration from disk. Some of the program modules activated
in this way open up a dialogue with {\sl you}, and allow you to expand
in an unlimited way the repertoire of things that \cam\ can be told to do.

\medskip

The most ``uncontrolled'' way for you to gain control is (a) to summon
(via the \cxp\ \keyF\ command) the {\sl Forth interpreter}, through
which all of the system's resources (\pc\ and \cam) become directly
accessible; at that point you are in charge, with all the advantages but
also all the burden that this entails.  Except for occasional {\sl
impromptu} interventions, you'd rather be able to (b) compose the
``score'' (cf.\ Section \ref{stack}) at your leisure and (c) give it to \cam\ to perform (with the
appropriate tempo) whenever you wish.  These needs are addressed
respectively by the {\sl screen editor}\index{Forth/editor} (summoned
by the \keyE\ command) and the {\sl loader}\index{Forth/loader}
(summoned by \keyL).


\medskip

In the rest of this chapter we'll briefly describe the procedures for
accessing the Forth interpreter, the loader, and the editor from the
\cp. More detailed information on the use of these programming resources is
given in the following chapters and in some of the appendices.

\section{Accessing the Forth interpreter}\label{access-forth}

From the \cp, the {\sl Forth} command (\icp\keyF\ or \icp\keyf\ keys)
allows you to enter into direct conversation with the Forth interpreter;\index{Forth/interpreter}
the \cxp\ prompt---namely the ``happy face''---disappears and the
interpreter itself will prompt you with an \iprog{ok}\index{Forth/prompt} (or an appropriate
error message) after processing each line you enter at the keyboard (see
Chapter \ref{tuto}).  As usual, \icp\keyesc\ returns you to the
\cp.\index{Break key}\footnote
    {This key is sensed only when the system is waiting for keyboard
input; to forcibly interrupt execution of a Forth word, use
\keybreak (cf.\ Section \ref{typing}).}

\section{Accessing DOS, and returning to DOS}\label{access-dos}

The normal way to leave the \prog{CAM} program and return to DOS
is to go to the Forth interpreter and type 
\iprog{BYE}.\index{DOS/returning to}

It is also possible to execute DOS commands without abandoning the
\prog{CAM} program.  From the \cp, the \keytilde\ key will access the
DOS command interpreter; typing \iprog{EXIT} will return control to the
panel.  DOS can also be accessed from Forth, as explained under
\iprog{EXEC}, \iprog{COM}, and \iprog{DOS...} in the glossary.\index{DOS/from Forth}

\section{Program files}\label{program files}

Early implementations of Forth, where a full-blown disk operating system
was not available or desirable, let Forth directly manage the contents
of the disk.  For this purpose, the entire disk was organized as a
collection of sequentially-numbered {\sl blocks} of 1024 bytes each.\index{Forth/block}

The present F83 implementation uses DOS as an operating system, thus
indirectly providing all of the DOS services.  In particular, a Forth
program can access an arbitrary number of named files.\index{File}  However, within
each of these files the traditional block structure is
retained.\footnote
        {Future implementations will likely drop the block structure for
text files entirely.}

\medskip

Blocks used for storing Forth code or other text material are called
{\em screens} (for this reason, a block file may also be called
a ``screen file'').  Each 1024-character screen is logically organized as 16
lines of 64 characters each.  Since all lines have the same
length, lines are not terminated by an end-of-line control character
as in conventional text files.\footnote
        {For this reason, attempting to view or list a Forth screen file
using the ordinary DOS facilities such as \prog{TYPE}, \prog{COPY} to printer
device, etc.\ yields unreadable results (the whole file looks like
a single unbroken line). Forth's own listing facilities
are discussed in Section \ref{listing}.}

The numbering of screens within a file starts from 0.  However, screen 0
itself cannot be interpreted by the loader (though it can be edited,
listed, used as virtual memory, etc.).  This screen is typically used
for extended comments (e.g., a brief description of the file's contents,
or directions for its use).

\medskip

For mnemonic convenience, all program files in the \cam\ Forth system
have been given extension \prog{4TH}---except for \cam\ experiments,
which have extension \prog{EXP}.

\section{The loader}\label{enter-loader}

{\sl Loading} a screen or a sequence of screens has essentially the same
effect as typing their contents from the keyboard at the
Forth interpreter level.\index{Forth/loader}  For anything that involves typing more than a
dozen words of Forth it is more convenient and reliable to compose the
text using the screen editor, save it in a screen file, and from there
feed it to the interpreter by means of the loader.

\medskip

The loading commands are\index{Control-panel commands/loading}
        \begin{equation}
        \begin{tabular}{|c|p{8cm}|} \hline
        \icp\keyl & {\sl Load}. Load the current file. \\ \hline
        \icp\keyL & {\sl Load new}. Load a specified file, and make it the current file. \\ \hline
        \end{tabular}
        \end{equation} The command \keyL\ is used for loading an
experiment from disk; it works in a way analogous to \keyG\
(which is used for loading a screen pattern; cf.\ Section
\ref{disk-io}).  \keyL\ prompts you to type the name of the desired
experiment file, and supplies the default extension \prog{EXP} to the
file name you type.

The \cxp\ loader first prints all nonblank lines from screen 0 of the
file, as a comment, and then loads all the screens from 1 on.

When a file is loaded with \keyL\ (or edited with \keyE), its name is
stored in the {\sl current-file} \index{File/current} register.  The
lower-case command \keyl\ has the same effect as \keyL, but looks in that
register for the file name,\footnote
    {The \cp\ will complain if you type \keyl\ when no file has yet
been made current: you must first explicitly
supply a file name with \keyL\ or \keyE.}
        so that you don't have to type it again if
you subsequently want to access the same file.  (Typically, you may
want to make a minor change in the file and try the experiment
again).

\medskip

As with \keyG, you can request a directory listing of all \prog{EXP} files,
or of all files matching a certain template.
If you enter a {\sl Load} command by mistake there are two ways of
getting out of it.  If the \cp\ is waiting for you to type the name of a
file, just type \keyesc---the\ usual way to return to the \cp.  If
loading has already started, you can type \keybreak\index{Break key}
(cf.\ Section \ref{typing}) to abort the loading.

\medskip

If \keyL\ or \keyl\ is preceded by a numeric argument $n$, instead of
the whole file only screen number $n$ is loaded (but see \id|-->|,
\id|THRU|, \id|+THRU|, and \id|INCLUDE| in the glossary), and the comments on screen
0 are not printed.

\section{The editor}\label{enter-editor}

The commands to enter the screen editor are:\index{Control-panel commands/screen editor}

 \begin{equation}
  \begin{tabular}{|c|p{8cm}|} \hline
   \icp\keye & {\sl Edit}. Edit the current file. \\ \hline
   \icp\keyE & {\sl Edit new}. Edit a specified file, and make it the current file. \\ \hline
  \end{tabular}
 \end{equation}

As with the {\sl Load} commands, a numeric argument specifies a screen
number---in this case the screen to be edited.  If you specify a screen
number past the end of the file, you will begin editing at the last
screen of the file.  If \keyE\ is used without an argument, the editor
starts at screen 1. As with \keyL, you can get a
directory listing by using wildcard characters in the filename, or by
hitting \keyreturn\ instead of typing a file name.

If the file name specified with \keyE\ doesn't already exist, the program
will offer to create a file with that name, initially consisting of two
blank screens.  

\medskip

An editing session is terminated by typing \icp\keyesc\ (any modified
screens are automatically saved to disk either during the session
or at the end of it).  The editor
remembers at what screen and cursor position you were when you exited
it.  If you subsequently re-enter the editor by typing \keye\ with no
argument, you return to where you left off.

\medskip

You also enter the editor automatically if an error is encountered
during loading---in this case the cursor will be positioned at the
point just after where the error was detected, and an error message
will appear below the editing window.\footnote
        {The most likely error is for the loader to
encounter an undefined word; in this case the error message is simply a question mark.}

\medskip

The commands available from within the editor are explained in Chapter
\ref{editor}.

\section{CAM programming}\label{cam-programmming}

The editor and loader together allow the construction and use of your own
\cam\ experiments. The editor is discussed in detail in Chapter \ref{editor}.
Chapter \ref{util} discusses a number of utilities mostly concerned
with program maintenance.

The remainder of this manual is devoted to explaining how to write your own
\cam\ experiments. We begin with a Forth tutorial, in the next chapter.\footnote
    {This is a slightly extended version of the tutorial appearing in
the \cambook.}
Part III is devoted to the programming of \cam\ itself.

\section{F83}\label{F83}

Incidentally, among the pieces of software distributed with \cam\ you'll
find the base F83 system---i.e., ``Forth without \cam''---with some
revisions and improvements over Perry and Laxen's original {\sl F83
model}.

You enter this bare F83 system by typing \prog{F83} at the DOS level (make sure that
the file \iprog{F83.EXE} is on line); \iprog{BYE} returns you to DOS.\index{DOS/returning to}

 


