\chapter{Miscellaneous utilities}\label{util}  % -*- Mode:TeX -*-

It is possible to program \cam\ entirely from the \cp, without ever
conversing directly with the Forth interpreter.  However, a number of
miscellaneous commands and utilities that pertain chiefly to system
maintenance are not individually attached to \cxp\ keys, and are meant
to be used interactively at the Forth-interpreter level.  Some of these
(seeing, listing, moving screens around, etc.)  are going to be valuable
even to the most casual user.

\section{Viewing and seeing}\label{view}

If you have the source code on line (see Section \ref{hard}), you can look at the definition of
any Forth word in the \cam\ system by using the \iprog{VIEW}
command.\index{Forth/word locator}  For example,  \id|VIEW DUP|
will list the definition for the {\sc code}
\index{Forth/code{\sc code}}
word \id|DUP|.
Once you have accessed the desired screen, you can use the following
words to move to adjacent screens\index{Shadow screen}:
        \begin{equation}
\begin{tabular}{|c|p{8cm}|} \hline  
{\tt L} & List the same screen again \\ \hline
{\tt N} & List the next screen \\ \hline
{\tt P} & List the previous screen \\ \hline
{\tt T} & Toggle between the current screen and its shadow. \\ \hline
\end{tabular}
        \end{equation}

\medskip

In addition to \iprog{VIEW}, which looks at the disk source,
there is a decompiling utility, \iprog{SEE},
which looks at the compiled version of a word (in memory)
and tries its best at reversing the compilation process.\index{Forth/decompiler}
For example, 
        \begin{verbatim}
    SEE LIST\end{verbatim}
        will decompile the word \id|LIST| (try it!).  This works well
with {\sc colon} words, {\sc constants}, {\sc variables}, etc.  For
{\tt DEFER}red\index{DEFER{\tt DEFER}} words (execution vectors), \id|SEE| knows how to call
itself recursively to track down the definition.  For {\sc code} words
such as \id|DUP|, \id|SEE| will tell you that they are in machine code,
but won't try to disassemble it (cf.\ \id|VIEW| above).

\medskip

If you are trying to trace the purpose of some Forth word and you are
unable to \iprog{VIEW} some of the words called by it, it's probably because
they are in some vocabulary that isn't part of your current
search order (Section \ref{search-order}).
Until you figure out the \iprog{ONLY}/\iprog{ALSO} business that
this Forth implementation uses for managing vocabularies, all you need
to know is that you can find out what vocabularies contain a given
word such as \iprog{SHOW} (useful for listing Forth code to the printer) by
typing
        \begin{verbatim}
    VOC SHOW\end{verbatim}
        Forth will respond by telling you that \iprog{SHOW} has definitions in
both the \iprog{FORTH} and \iprog{SHADOW} vocabularies.  To \iprog{VIEW} its
definition in the \id|SHADOW| vocabulary, type
        \begin{verbatim}
  SHADOW VIEW SHOW\end{verbatim}

To see a list of all vocabularies, type 
        \begin{verbatim}
    VOCS\end{verbatim}
        To see a list of all words in a given vocabulary, say, \id|SHADOW|, type
        \begin{verbatim}
    SHADOW WORDS\end{verbatim}
        To see the current search order, type
        \begin{verbatim}
    ORDER\end{verbatim}

Finally, 
        \begin{verbatim}
    'USED MY-WORD\end{verbatim}
        will list all the words that use \id|MY-WORD| in their definition
(cf.\ glossary).

\section{The current file}\label{current}

We have seen that a file is automatically opened and made the {\sl
current} file\index{File/current} when it is accessed from the \cp\ via \keyE\ or \keyL\
(note that \iprog{VIEW} does {\sl not} affect the current file).
From Forth, if you want to open a file called \prog{FOO.BAR} you
type
        \begin{verbatim}
    USING FOO.BAR\end{verbatim} (or perhaps {\tt A:FOO.BAR} if you wish to
specify the drive).  If no extension is specified, \iprog{USING} will
add the default extension \prog{EXP} to the filename.  As with \keyE\ and
\keyL\ in the \cp, wildcard characters or no filename results in a
directory listing.  The Forth words \prog{A:}, \prog{B:}, and \prog{C:}
can be used to change the default drive selection.

To move one's attention to a new file, one simply opens that file; the
explicit closing of a block file (cf.\ Section \ref{program files}) is not required.
{\sl Avoid using \iprog{OPEN} (the usual F83 word for opening a file)---as it
can produce unexpected results if followed by the execution of
\iprog{NEW-EXPERIMENT} or \id|FORGET|.}

If the file name given to \iprog{USING} does not already exist, the
program offers to create it; the initial size of this file will be two
blocks\index{Forth/block}, corresponding to two screens of text. 

\medskip

The word \iprog{CAPACITY} returns the number of blocks that make up
the current file. 

To add 10 more blocks to the end of the file, simply type
        \begin{verbatim}
    10 MORE\end{verbatim}
To remove 2 blocks, you type
        \begin{verbatim}
    2 LESS\end{verbatim}
To insert 2 blocks right before the screen that was edited last (in order, say, to insert
some new text), type
        \begin{verbatim}
    2 INS-SCR\end{verbatim}

\section{Editing}\label{util-edit}

To enter the screen editor from Forth and edit,\index{EDIT{\tt EDIT}} say, screen 7 of the current file, type
        \begin{verbatim}
    7 EDIT\end{verbatim}
        To re-enter to the editor from Forth,\footnote
        {Note that \ied\keyesc\ will return you to the Forth interpreter (rather
than the \cp) if you entered the editor from there.}
        just type
\id|...| (``dot-dot-dot'')---a Forth word meaning ``resume editing.'' 

\medskip

There is an additional, ``contents-addressed'' way to enter the editor,
namely, by using the word \iprog{FIX}.

If \prog{XYZ} is a word that has been compiled into the dictionary by
loading a screen file, the compiled version of the word will contain a
pointer (called {\sl view field\/}) to the file and screen it ``came
from'' (i.e., to its source); typing
        \begin{verbatim}
    FIX XYZ\end{verbatim}
will enter the editor with the cursor positioned right after
the word \prog{XYZ}. For this to work, the relevant source file
must be on-line on the expected drive (cf.\ Section \ref{hard}), or you'll get an \id|Open error| message.

For example, the word \prog{FIX} itself was loaded into the Forth dictionary
from the source file \prog{PC.4TH}; if this file is accessible, typing
        \begin{verbatim}
    FIX FIX\end{verbatim}
        will set you up for editing the definition of \prog{FIX}.
In a similar way, if the word \prog{DUMMY} was just loaded from the
current file, typing \prog{FIX DUMMY} will set you up
for editing its definition in that file.\footnote
        {\prog{FIX} can find source code in one of the \prog{F83} or
\prog{CAM} source files; otherwise it looks in the current file.  If
after loading a word you change the current file, \prog{FIX} will look
for that word in the ``right place'' but in the wrong file.}

\section{Loading}\label{util-load}

From the \cp, the commands \keyl\ and \keyL\ allow one to {\em load}---i.e.,
submit to the Forth interpreter (cf.\ Section \ref{editing-loading})---an entire file
or, when the command is preceded ny a numerical argument, a single screen
of that file. From Forth, to load, say, screen 7 of the current file,\index{LOAD{\tt LOAD}}
type
        \begin{verbatim}
    7 LOAD\end{verbatim}
        To load screens 7--9, type
        \begin{verbatim}
    7 9 THRU\end{verbatim}
        In particular, to load the entire file you have to type
        \begin{verbatim}
    1 CAPACITY 1- LOAD\end{verbatim}
        which, admittedly, is a bit awkward. Note that (a) screen 0 of a file
can never be loaded, and is usually reserved for comments; and (b) \id|CAPACITY|
returns the size, in screens, of the current file, so that a 10-screen file
will yield a \id|CAPACITY| of 10 but will have its screens numbered 0 through 9!

\section{Listing}\label{listing}

Files having the extension \id|DOC| are ordinary \pc\ text files, and
should be listed using the appropriate DOS utilities.

To inspect the contents of a Forth block file (Section \ref{program
files}), the simplest way is of course to use the screen editor (for
blocks that contain arbitrary data rather than text, cf.\ end of Section
\ref{editing}).

From Forth, \id|7 LIST| will list screen 7 of the current file on the
monitor without going through the screen editor.\index{File/listing} This
will work well only for {\em text} screens.

The first line of a text screen usually contains a comment describing
the contents of that screen.  The phrase

\medskip

 $\langle$first screen$\rangle$ $\langle$last screen$\rangle$ \iprog{INDEX}
\medskip

\noindent produces an ``index'' consisting of the first lines
of all screens of the current file within the specified range.

Anything that is sent to the monitor by the Forth interpreter can be
additionally routed to the printer, using \iprog{PRINTING}. Thus, if you want a hardcopy
of the index of screens 10--15, you type
        \begin{verbatim}
        PRINTING ON   10 15 INDEX   PRINTING OFF\end{verbatim}
        and the index will be sent both to the screen and to the printer.

\medskip

The two ``listing'' words \prog{SHOW} and \prog{LISTING} send their
output only to the printer, preceded by a control code that sets the
printer to compressed mode (132 characters/line); check
that the Forth system knows what kind of printer you are using (cf.\ Appendix
\ref{custom-screens}).

\iprog{SHOW} is used to {\sl print} a listing of any
consecutive portion of the current file, with the following syntax

\medskip

 $\langle$first screen$\rangle$ $\langle$last screen$\rangle$ \prog{SHOW}

\medskip
\noindent (If you want to print the whole file, type
\id|0  CAPACITY 1-  SHOW|.)

On the other hand, \iprog{LISTING} (with no arguments) assumes that the
current file is organized as ``source'' and ``shadow''
screens\index{Shadow screen} (cf.\ Section \ref{util-edit}), and produces a
complete listing of the file with source and shadow screens
side-by-side. \id|SHOW| can also be used in this fashion, by saying,
for example, \id|1 10 SHADOW SHOW|.

\section{Moving screens around}\label{moving screens}

The editor commands {\sl Kill}, {\sl Wipe}, and {\sl Yank} are adequate
for moving around a few words or lines, perhaps up to one screenful; the
{\sl Copy} command is used for making a copy of the entire current file
to a newly created file.  For moving several screens, \iprog{CONVEY} is
useful: to move screens 3--10 of file \prog{SOURCE.EXP} to the current
file, starting at screen 12 (and thus overwriting screens 12--19 of the
current file), you type
        \begin{verbatim}
    FROM SOURCE.EXP 3 10 TO 12 CONVEY\end{verbatim}
\prog{CONVEY} can also be used, of course, to move screens within the same file.
For overlapping source and destination ranges, \id|CONVEY| does the right thing.

\medskip

{\small The clause \prog{FROM SOURCE.EXP} makes \prog{SOURCE.EXP} the {\sl from} file
(``from'' and ``current'' are two distinct ``slots'' managed by F83
for dealing with whatever files are relevant at the moment); if
\prog{SOURCE.EXP} had already been declared
as the {\sl from} file, this clause may be dropped.

Note that, when you open a file, the {\sl from} ``slot'' (as well as the
{\sl current\/} ``slot'') is assigned by default to this file; thus
        \begin{verbatim}
    3 10 TO 12 CONVEY\end{verbatim}
        (with no explicit \prog{FROM} clause) will copy to screens
12--19 of the current file screens 3--10 of the {\sl same} file, {\sl
provided that you have not reassigned the {\rm from} ``slot'' since you
opened the current file}.

}%end \small

\medskip

\prog{CONVEY} is not allowed to change the length of the destination
file.  If this file is too short, it must be lengthened first (using
\iprog{MORE}, for instance) so that the screens to be conveyed
may fit in. 


\section{Moving files around}\label{moving files}

In addition to the above utilities, you can always use the utilities
provided by DOS for erasing, copying, and renaming files, etc.
As mentioned in Section \ref{access-dos}, the DOS command interpreter can be accessed
from within \cam\ Forth.













