\documentstyle[twoside,12pt]{article}

\newcommand{\adjusttextheight}{
\setlength{\textheight}{29.7cm}         % DIN A4 paper height
\addtolength{\textheight}{-1.7cm}       % inaccessible space
\addtolength{\textheight}{-1in}
\addtolength{\textheight}{-\topmargin}
\addtolength{\textheight}{-\headheight}
\addtolength{\textheight}{-\headsep}
\addtolength{\textheight}{-\topskip}
\addtolength{\textheight}{-\footheight}
\addtolength{\textheight}{-\footskip}
}

\newcommand{\adjusttextwidth}{
\setlength{\textwidth}{21cm}    % DIN A4 paper width
\addtolength{\textwidth}{-1in}
\addtolength{\textwidth}{-\oddsidemargin}
\addtolength{\textwidth}{-1in}
\addtolength{\textwidth}{-\evensidemargin} }



\setlength{\topmargin}{-0.5cm}
\setlength{\footskip}{0cm}
\adjusttextheight
\setlength{\evensidemargin}{0cm}
\setlength{\oddsidemargin}{0cm}
\adjusttextwidth


\newcommand{\Arcgsh}{{\em Arcgsh\/}}
\newcommand{\arc}{{\em arc\/}}
\newcommand{\Arc}{{\em Arc\/}}
\newcommand{\lharc}{{\em lharc\/}}
\newcommand{\Lharc}{{\em Lharc\/}}
\newcommand{\shar}{{\em shar\/}}
\newcommand{\Shar}{{\em Shar\/}}
\newcommand{\tar}{{\em tar\/}}
\newcommand{\Tar}{{\em Tar\/}}
\newcommand{\zoo}{{\em zoo\/}}
\newcommand{\Zoo}{{\em Zoo\/}}
\newcommand{\compress}{{\em compress\/}}
\newcommand{\Compress}{{\em Compress\/}}
\newcommand{\uud}{{\em uud\/}}
\newcommand{\Uud}{{\em Uud\/}}
\newcommand{\uue}{{\em uue\/}}
\newcommand{\Uue}{{\em Uue\/}}

\newcommand{\field}[1]{{\sf ``#1''}}
\newcommand{\menu}[1]{{\sf ``#1''}}
\newcommand{\button}[1]{{\setlength{\fboxsep}{1pt}\framebox{\sf #1}}}

\pagestyle{headings}
\flushbottom
\sloppy

\title{
{\bf ARCGSH}\\
Archiver GEM Shell\\
--- Version 4.0 ---
}

\author{
Dipl.-Inform. Rainer Klute\\
Vinckeplatz 5\\
D--W4600 Dortmund 1\\
\normalsize klute@irb.informatik.uni-dortmund.de
}

\date{January 17, 1992}




\begin{document}

\thispagestyle{empty}

\maketitle

\newpage

\tableofcontents

\newpage




\section{Changes since version 3.5}

\begin{itemize}

\item {\Arcgsh} supports {\tar} and {\compress} now. The manual has been
updated accordingly.

\item {\Arcgsh} supports {\zoo} 2.1 now, especially the new {\bf h} option to
achieve high performance compression.

\item The use of {\lharc} has been considerably improved. {\Arcgsh} can be
adopted to each and every {\lharc} program. See section \ref{LHarc} (page
\pageref{LHarc}) for details.

\end{itemize}




\section{Copyright}

\begin{center}
{\large \bf Copyright 1991 Rainer Klute}
\end{center}

Permission to use, copy, and distribute {\Arcgsh} and its documentation for
any purpose and without fee is hereby granted, provided that the above
copyright notice appears in all copies and that both that copyright notice
and this permission notice appear in supporting documentation. The file {\tt
ARCGSH.CFG} is explicitly excluded from the permission to distribute. I do
not make representations about the suitability of this software for any
purpose. It is provided ``as is'' without express or implied warranty.




\section{Introduction}

{\Arcgsh} is a GEM shell that eases the use of the most popular archiving
programs for the Atari ST ({\arc}, {\lharc}, {\shar}, {\tar}, and {\zoo}).
Furthermore the programs \compress, \uud, and \uue are supported. {\compress}
is able to compress resp. decompress a single file. {\uud} and {\uue} are
useful if binary files --- e.\,g. archives --- are to be sent or received
with electronic mail. What is more: You can use your favorite file viewer
and your favorite editor from {\Arcgsh} without any need to leave the
program.

With {\Arcgsh} it is no longer neccessary to start a command-line-shell in
order to run an archiver, ``cd'' to the directory where your archive file is
(or should be created), remember the various archiver options (each archiver
has its own set of options), type them in and finally start the program.
With {\Arcgsh} you can handle everything with GEM objects:  Dialog boxes let
you select program options via buttons, and filenames are comfortably
selected using the GEM file selector box.

{\Arcgsh} is a shell, not a stand-alone program. In order to make use of the
various archiving programs, you must at first have them installed somewhere
on your computer. This is what you need:

\begin{center}
\begin{tabular}{lll}
{\bf Programm} & {\bf Dateiname}    & {\bf atari.archive} \\
\hline
\arc           & {\tt ARC.TTP}      & /atari/archivers/arc602.ttp \\
\lharc         & {\tt LHARC.TTP}    & /atari/archivers/lzh201i.lzh \\
\shar          & {\tt SHAR\_RK.TTP} & /atari/archivers/shar\_rk.arc \\
\tar           & {\tt GNUTAR.TTP}   & /atari/gnustuff/tos/gnutar/gtarbin.zoo \\
\zoo           & {\tt ZOO.TTP}      & /atari/archivers/zoo21bin.zoo \\
               &                    & \\
\compress      & {\tt COMPRESS.TTP} & /atari/archivers/compress.zoo \\
\uud           & {\tt UUD.TTP}      & /atari/archivers/uux789.zoo \\
\uue           & {\tt UUE.TTP}      & /atari/archivers/uux789.zoo \\
\end{tabular}
\end{center}

{\small
\begin{quotation}

What does {\bf atari.archive} mean? Well, those of you who have access to
the international Internet can retrieve files by anonymous FTP from the FTP
server atari.archive.umich.edu of the University of Michigan (USA).
Archiving programs can be found there in the directory {\tt
/atari/archivers}. The table above refers to files within this directory at
atari.archive.umich.edu. (If you do not understand what I am talking about
you probably have not Internet access. You can get the files you need from
me on a disk then.)

\end{quotation}
}




\section{The usual shareware plea}\label{The usual shareware plea}

However, if you find {\Arcgsh} useful and use it regularly you are encouraged
to transfer {\bf DM 35,--} to my bank account {\bf 4412\,46-300} at the {\bf
Postgiroamt Hannover, BLZ 250\,100\,30} in Germany. Alternativly you can
send me a cheque or money order made out in your own
currency\footnote{Making out the cheque or money order in your currency
minimizes the transfer costs.}.

A dialog box will pop up from time to time to remember you to pay the
shareware fee. You may well ignore it (resp.\ click it away) without having
to have a bad conscience. However, if you are so kind to send me the
shareware fee I shall tell you how you can get rid of those dialog boxes to
appear. Furthermore the {\em xArgv\/} and {\em ARGV} extended parameter
passing schemes will be activated for you. They are useful if you want an
archiver to handle a long list of file names because {\em xArgv\/} and {\em
ARGV\/} allow you to pass long parameter strings (more than 125 characters)
to dependend programs (archivers).

Please do not forget to mention your name and address (e-mail address
preferred)! I cannot get in contact with you if you forget them!




\section{Some general remarks}

{\Arcgsh} does its job by calling other programs, usually archivers. These
programs are subsequently referred to as {\bf dependent programs.} The
calling of such programs follows a common scheme.  Here only a short outline
is given; detailed explanations you can find below.

\begin{itemize}

\item Select the program you want to start from the \menu{File} menu,
e.\,g.\ \menu{Zoo ...}.

\item A dialog box will show up where you have to specify the program
parameters.  This can be done by clicking at buttons, selecting filenames or
typing text into fields.

Many text fields serve to hold a filename or folder name. If you doubleclick
at such a field the GEM file selector box will show up and let you select a
file resp.\ folder. If the field does not hold any text a single click is
sufficient to let the file selector box appear. Does the field contain some
text already a single click only positions the text cursor into the field
and allows editing of the text.

To select a {\bf folder} just navigate the file selector box into that
folder, select any file or simply click at \button{OK}.

The selector box automatically appears to select a mandatory filename
parameter, e.\,g.\ the archive file handled by an archiver.

For further details on filename fields refer to section \ref{The file
selection handler} (page \pageref{The file selection handler}).

\item Execution of the selected dependent program starts when you click at the
\button{OK} button in the parameter dialog box.  If the dependent program is
of type TOS or TTP the screen is cleared and switched to alphanumeric mode
before launching the program.  If {\Arcgsh} does not know where the program
resides it will display the GEM file selector box asking you to locate the
program.

\item Upon termination of the dependent program {\Arcgsh} will (optionally)
beep to let you know about the termination (very useful for long-running
programs).  The dependent program's output is (optionally) kept on the
screen until you press any key or click with the left mouse button.

{\bf Beware:} If an error occurred the dependent program itself may hold the
screen and ask you to type any key. In this case you will have to hit the
key twice: once for the dependent program and once for {\Arcgsh}.  If the
dependent program exits with a return code not equal to zero that code will
be displayed in an alert box.

\end{itemize}




\section{The Arcgsh menus}

When you start up {\Arcgsh} you will see a menu bar like this:

\begin{tabular}{@{}|lllll|}
\hline
{\sf ~ARCGSH~} & {\sf ~File~} & {\sf ~Configuration~} & {\sf ~Utilities~} & {\sf ~Options~} \\
\hline
\end{tabular}

\noindent The subsequent paragraphs will explain the individual menus.




\subsection{The ``ARCGSH'' menu}

\begin{tabular}{@{}l@{}llll@{}}
\hline
\vline {\sf ~ARCGSH~} & {\sf ~File~} & {\sf ~Configuration~} & {\sf ~Utilities~} & {\sf ~Options~} \hfill \vline\\
\hline
\vline {\sf ~About~Arcgsh~...~} \vline & & & &\\
\cline{1-1}\\
\end{tabular}

\noindent This menu shows at its first position the entry \menu{About Arcgsh
...}. If you select this menu item a dialog box will pop up showing you some
general information about the program and its author.




\subsection{The ``File'' menu}

\newlength{\pl}
\settowidth{\pl}{\sf ~Other~program~...  p~}
\begin{tabular}{@{}l@{}l@{}lll@{}}
\hline
\vline {\sf ~ARCGSH~} & {\sf ~File~} & {\sf ~Configuration~} & {\sf ~Utilities~} & {\sf ~Options~} \hfill \vline\\
\hline
& \vline \parbox{\pl}{\sf ~Arc~...           \hfill a~} \hfill \vline & & &\\
& \vline \parbox{\pl}{\sf ~LHarc~...         \hfill l~} \hfill \vline & & &\\
& \vline \parbox{\pl}{\sf ~Shar~...          \hfill  ~} \hfill \vline & & &\\
& \vline \parbox{\pl}{\sf ~Tar~...           \hfill t~} \hfill \vline & & &\\
& \vline \parbox{\pl}{\sf ~Zoo~...           \hfill z~} \hfill \vline & & &\\
\cline{2-2}
& \vline \parbox{\pl}{\sf ~Compress~...      \hfill c~} \hfill \vline & & &\\
\cline{2-2}
& \vline \parbox{\pl}{\sf ~Uud~...           \hfill u~} \hfill \vline & & &\\
& \vline \parbox{\pl}{\sf ~Uue~...           \hfill  ~} \hfill \vline & & &\\
\cline{2-2}
& \vline \parbox{\pl}{\sf ~Other~program~... \hfill p~} \hfill \vline & & &\\
\cline{2-2}
& \vline \parbox{\pl}{\sf ~Show~file~...     \hfill s~} \hfill \vline & & &\\
& \vline \parbox{\pl}{\sf ~Edit~file~...     \hfill e~} \hfill \vline & & &\\
\cline{2-2}
& \vline \parbox{\pl}{\sf ~Quit              \hfill q~} \hfill \vline & & &\\
\cline{2-2}\\
\end{tabular}

\noindent The \menu{File} menu is the one you will use to get the archivers
to work. The meaning of the menu items is as follows:

\begin{description}

\item[\menu{Arc ...}, \menu{LHarc ...}, \menu{Shar ...}, \menu{Tar ...},
\menu{Zoo ...}:]  These are the names of the archivers {\Arcgsh} supports. If
you want to start one of them select it from the \menu{File} menu. A
archiver-specific dialog box will appear and you can select filenames,
options, etc. Please refer to the individual descriptions in section
\ref{How to use the archivers} (page \pageref{How to use the archivers})!

\item[\menu{Compress ...}:] The program {\compress} can be used to compress
or decompress a single file. Usually compressed files have the letter {\tt Z}
as the last letter in their names. For details refer to section
\ref{Compress} (page \pageref{Compress}).

\item[\menu{Uud ...}, \menu{Uue ...}:] Binary files (e.\,g. archive files or
programs) can usually not be transferred via electronic mail directly. They
have to be ``uuencoded'' first, which can be achived with the program
{\uue}. It encodes a file in such a way that the encoded file consists of
printable characters only, which will (hopefully) not be mangled by any
mailers.

{\Uud} on the other hand allows you to ``uudecode'' uuencoded files. It is
most useful to decode files you have received via news or e-mail. A single
uuencoded file usually has {\tt .UUE} as its file name extension. 

To uuencode resp. uudecode a file select one of the \menu{uud} or \menu{uue}
menu entries.  A dialog box will pop up which allows you to select the
various parameters of {\uud} resp.\ {\uue}. For details refer to section
\ref{Uud and uue} (page \pageref{Uud and uue}).

\item[\menu{Other program ...}:] A dialog box will pop up and allows to
select any other program you want to execute. It is also possible to give
parameters to that program and also choose its working directory. For
details refer to section \ref{Calling other programs} (page \pageref{Calling
other programs}).

\item[\menu{Show file ...}:] If you want to look at a file you can select
this menu item. However, {\Arcgsh} itself does not display the file but calls
another program, the {\bf user-defined pager}. You can use the pager program
you like best. For details refer to section \ref{The user-defined pager}
(page \pageref{The user-defined pager}).

\item[\menu{Edit file ...}:] You can use this menu entry to edit a file.
{\Arcgsh} does not have a built-in editor but allows you to use your own
favorite text editor. For details refer to section \ref{The user-defined
editor} (page \pageref{The user-defined editor}).

\item[\menu{Quit}:] terminate {\Arcgsh}.

\end{description}




\subsubsection{Invoking ``File'' menu dialogs from the
keyboard}\label{Invoking File menu dialogs from the keyboard}

Most \menu{File} menu dialogs can also be invoked from the keyboard. Just
type the key that is shown at the right hand side of the menu item, e.\,g.
{\sf ``z''} to make the {\zoo} dialog box appear on the screen.



\subsection{The ``Configuration'' menu}

\begin{tabular}{@{}ll@{}l@{}ll@{}}
\hline
\vline {\sf ~ARCGSH~} & {\sf ~File~} & {\sf ~Configuration~} & {\sf ~Utilities~} & {\sf ~Options~} \hfill \vline\\
\hline
& & \vline {\sf ~Locate~Arc~...~}       \hfill \vline & &\\
& & \vline {\sf ~Locate~LHarc~...~}     \hfill \vline & &\\
& & \vline {\sf ~Locate~Shar~...~}      \hfill \vline & &\\
& & \vline {\sf ~Locate~Tar~...~}       \hfill \vline & &\\
& & \vline {\sf ~Locate~Zoo~...~}       \hfill \vline & &\\
\cline{3-3}
& & \vline {\sf ~Locate~Compress~...~}  \hfill \vline & &\\
\cline{3-3}
& & \vline {\sf ~Locate~Uud~...~}       \hfill \vline & &\\
& & \vline {\sf ~Locate~Uue~...~}       \hfill \vline & &\\
\cline{3-3}
& & \vline {\sf ~Configure~pager~...~}  \hfill \vline & &\\
& & \vline {\sf ~Configure~editor~...~} \hfill \vline & &\\
\cline{3-3}
& & \vline {\sf ~Save~configuration~}   \hfill \vline & &\\
\cline{3-3}\\
\end{tabular}

\noindent Before {\Arcgsh} is able to execute a {\bf dependent programs},
e.\,g. an archiver, it must know where this program resides on disk.  You
can tell {\Arcgsh} the locations of the various programs with the
\menu{Configuration} menu.

Let us suppose you want to locate the {\zoo} archiver. First you have to
select the \menu{Locate~Zoo~...} menu item. The GEM file selector box
together with the prompt {\sf ``Locate program ZOO.TTP''} will be
shown\footnote{If you have at least TOS~1.4 the prompt will appear in the
file selector box; if you still have an older TOS version it will be
displayed in the menu bar.}. Now you can navigate the file selector to the
directory where {\tt ZOO.TTP} resides, select {\tt ZOO.TTP} and click at
\button{OK}. From now on {\Arcgsh} knows where it can find {\tt ZOO.TTP}.

The menu items \menu{Configure pager ...} and \menu{Configure editor ...}
let you choose a program you want to use to look into files resp.\ to edit
files.

{\bf Example:} You want to configure 1st Word Plus (filename {\tt
WORDPLUS.PRG}) as your editor. When you select \menu{Configure editor ...} a
dialog box will appear and --- if you do not have selected an editor yet ---
immediately afterwards the GEM file selector with the prompt {\sf ``Locate
user-defined editor''} pops up. The first line of the file selector shows
you that only files called {\tt EDITOR.PRG} will be displayed. As this is
inappropriate to select {\tt WORDPLUS.PRG} you have to change {\tt
EDITOR.PRG} to {\tt WORDPLUS.PRG} (or to {\tt *.*} in order to display every
file).  The file selector now shows all files named {\tt WORDPLUS.PRG}, you
can navigate it through your file system and select {\tt WORDPLUS.PRG} as
described above for {\tt ZOO.TTP}.

After you have selected the editor you can still modify the command
{\Arcgsh} uses to call the editor. By default the editor will be called with
one parameter: the name of the file to be edited. This filename is
represented by {\tt \%f} in the \field{Parameters ...} text edit field. Say
you want to give the additional options {\tt -l} and {\tt -w} to the editor.
You have to change the text edit field to {\tt -l~-w~\%f} then.

Of course you would not like to locate every program once again every time
you start {\Arcgsh}. The program locations can be saved on disk with the
\menu{Save configuration} menu item. {\Arcgsh} creates the file {\tt
ARCGSH.CFG} in the same directory as {\tt ARCGSH.PRG} and writes all
neccessary information into it.



\subsection{The ``Utilities'' menu}

\begin{tabular}{@{}lll@{}l@{}l@{}}
\hline
\vline {\sf ~ARCGSH~} & {\sf ~File~} & {\sf ~Configuration~} & {\sf ~Utilities~} & {\sf ~Options~} \hfill \vline\\
\hline
& & & \vline {\sf ~Copy~file~...~}     \hfill \vline &\\
& & & \vline {\sf ~Move~file~...~}     \hfill \vline &\\
& & & \vline {\sf ~Delete~file~...~}   \hfill \vline &\\
\cline{4-4}
& & & \vline {\sf ~Create~folder~...~} \hfill \vline &\\
& & & \vline {\sf ~Delete~folder~...~} \hfill \vline &\\
\cline{4-4}\\
\end{tabular}

\noindent {\Arcgsh} offers you a very simple tool for basic file
manipulation.  You can copy, move\footnote{copy a file to another place and
delete the original} and delete a file, create and delete a folder by
selecting the corresponding menu item.  The file resp.\ folder names are
requested by the GEM file selector box.

\begin{description}

\item[\menu{Copy file}, \menu{Move file}:] These functions ask for the file
to be copied resp.\ moved with the GEM file selector box.  Then the file
selector box appears once again and asks for the destination filename. (As I
said, very simple.)

In case the file is to be copied/moved into another folder but with the same
basename\footnote{This is the ``essential'' last part of the filename
without drive and path specification.} it is sufficient to specify the
destination directory, not the full destination filename.  To do this
navigate the file selector box to the destination folder and simply click at
\button{OK}. You do not have to select or type any filename.

\menu{Copy file} and \menu{Move file} both preserve the creation date and
time of the file to be copied/moved as well as the file attributes
(read/write access or read-only access etc.)

Another word about the \menu{Move file} function:  If a file is to be moved
to another folder on the {\bf same} disk the \menu{Move file} function is
very efficient because the contents of the file itself does not have to be
copied.\footnote{The GEMDOS function {\tt Frename} is used.}

\item[\menu{Delete file}, \menu{Create folder}, \menu{Delete folder}:] These
functions do what their names say.  The GEM file selector box lets you
specify the desired file/folder name.

\end{description}



\subsection{The ``Options'' menu}\label{options menu}

\begin{tabular}{@{}llll@{}l@{}}
\hline
\vline {\sf ~ARCGSH~} & {\sf ~File~} & {\sf ~Configuration~} & {\sf ~Utilities~} & {\sf ~Options~} \hfill \vline\\
\hline
& & & & \vline {\sf ~Show~command~line~}     \hfill \vline \\
& & & & \vline {\sf ~Hold upon termination~} \hfill \vline \\
& & & & \vline {\sf ~Beep upon termination~} \hfill \vline \\
\cline{5-5}
& & & & \vline {\sf ~Repeat last dialog~}    \hfill \vline \\
& & & & \vline {\sf ~Zoom boxes~}            \hfill \vline \\
\cline{5-5}\\
\end{tabular}

\noindent By use of this menu you can influence the behaviour of {\Arcgsh}
when a dependent program --- e.\,g.\ an archiver --- is executed. Each of
these options can be {\bf active} or {\bf inactive}. An active option is
indicated by a check mark at the left side of the option text in the menu.
The meaning of the options is as follows:

\begin{description}

\item[\menu{Show command line}:] If this option is active {\Arcgsh} displays
the command line that is used to call the dependent program.  This option is
ignored for programs ending with {\tt .PRG} or {\tt
.APP}.

\item[\menu{Hold upon termination}:] If this option is active {\Arcgsh}
holds the screen before returning to the {\Arcgsh} desktop. This is useful
to see the messages the dependent program has written to the screen. Press
any key or click with the left mouse button to return to the {\Arcgsh}
desktop. This option is ignored for programs ending with {\tt .PRG} or {\tt
.APP}.

\item[\menu{Beep upon termination}:] If this option is active {\Arcgsh}
beeps when the dependent program terminates. This is useful when the
dependent program runs for a long time and you do not want to watch the
screen all the time to know whether it has terminated.

\item[\menu{Repeat last dialog}:] If this option is active, after having
performed a certain function {\Arcgsh} automatically shows the dialog box for
that function again. This is especially useful when an archiver has to be
called several times in succession. The cycle is stopped by the
\button{Cancel} button of the dialog box.

\item[\menu{Zoom boxes}:] If this option is active, a growing box is drawn
when a window is opened and a shrinking box when it is closed. When you
disable this option the ``zoom'' boxes are not drawn and you will get a
little speed gain in the dialogs.

\end{description}

The current options setting can be saved with \menu{Save configuration} in
the \menu{Configuration} menu.




\section{How to use the archivers}\label{How to use the archivers}

The calling of archivers follows a common scheme: First you select the
archiver you want to use from the \menu{File} menu. Then a dialog box
specifically designed for that particular archiver will pop up and you can
specify archiver parameters by clicking at buttons and entering filenames
with the GEM file selector box or with the keyboard. When you have selected
all the parameters you need click at \button{OK}. {\Arcgsh} will clear the
screen and run the program with the parameters you
specified\footnote{Passing parameters to an archiver or to a dependend
program in general can be done in different ways. See section \ref{Passing
parameters to a dependend program} (page \pageref{Passing parameters to a
dependend program}) for details.}.  If you have changed your mind not to
execute it click at \button{CANCEL}.

We will consider the different archivers now in some detail by use of
examples. However, you should remember that this manual is about {\Arcgsh}
and not about the archivers as such. I strongly recommend to read the
original archiver documentations!



\subsection{Zoo}\label{Zoo}

{\Zoo} is the archiver with the most features. {\Arcgsh} is known to work
together with {\zoo} version 2.1 ported to the Atari ST by Bill Shroka.



\subsubsection{Extracting a whole zoo archive file}

As our first example we want to extract a whole {\zoo} archive file. Its name
is {\tt EX1.ZOO}.

When you have selected the \menu{Zoo ...} menu item from the \menu{File}
menu the {\zoo} dialog box will pop up and allows you to enter {\zoo}
parameters.  The first parameter you have to select is the {\zoo} archive
file. You can do that with the GEM file selector box which will appear
automatically.  Navigate the file selector to the directory where {\tt
EX1.ZOO} is stored and select the archive file. The file selector box
disappears and the file name is shown in the \field{Archive} field.

To extract all files from the archive select \button{e~~extract files}. You
will notice that on the right hand side of the dialog box a lot of
\field{Zoo modifiers} will appear. By use of these modifiers you can
influence the {\zoo} extraction process.

For now we will not select a {\zoo} modifier but simply click at \button{OK}.
{\zoo} starts up, extracts every file from the archive and writes it to the
same directory where {\tt EX1.ZOO} is in.



\subsubsection{Extracting particular files from a zoo archive file}

Consider now that we do not want to extract {\bf all} the files stored in
{\tt EX1.ZOO} but only those with a particular name or name component, say
with the extension {\tt .C}.

Recall the {\zoo} dialog box by selection of the \menu{Zoo ...}\ menu item.
From the previous call the {\zoo} archive file is still selected so the GEM
file selector will not appear this time. Now we have to specify the files we
want to extract: Move the text cursor to the \field{Filename} field, type
{\tt *.C} into it, then click at \button{OK}.

In many cases the \field{Filename} field is sufficient to specify the files
you want to extract from an archive file. However, if you want to specify
more files or selection patterns you can click at \button{more files...}
This will make another dialog box --- the file selection handler --- to
appear. Here you have more fields to select filenames. You can even redirect
standard input, standard output and select a working directory for the
{\zoo} program. A detailed description of the file selection handler you
will find in section \ref{The file selection handler} (page \pageref{The
file selection handler}).



\subsubsection{Extracting from a zoo archive into another directory}

In the examples above the destination of extraction has always been the
directory where the archive file itself was in. Now we want to extract into
another directory.

When {\zoo} is executing it has a {\bf current directory} or {\bf working
directory}. Files that have no explicit drive and directory
specification\footnote{Example: In {\tt
A:$\backslash$FOO$\backslash$BAR$\backslash$EX1.ZOO} the part {\tt
A:$\backslash$} is the drive specification and {\tt
FOO$\backslash$BAR$\backslash$} is the directory specification.} are
addressed relative to this directory.  When {\zoo} extracts files it
(normally) creates them relative to the current directory.\footnote{A
special case is when files are stored in the archive with an absolute
pathname (except drive specification). This should be avoided.} The default
current directory is the folder the archive is in.  If we want to extract
into another folder we have to change the current directory. This can be
achieved by clicking at the \button{more files...} button in the {\zoo}
dialog box.

The dialog box that pops up now is the file selection handler. It is
described in detail in section \ref{The file selection handler} (page
\pageref{The file selection handler}). Here only the \field{Working
directory} field is of interest. Click at this field, see the GEM file
selector box appear, and select a directory to be the working directory. To
select it move the file selector {\bf into} that directory, then click at
\button{OK} in the selector box.

A click at the \button{OK} button of the file selection handler makes it
disappear. Proceed as described above now and {\zoo} will extract into the
selected directory.



\subsubsection{Adding files to a zoo archive}

To add files to a {\zoo} archive resp.\ to create a new archive you have to
select the \button{a~~add~files} button. If the {\zoo} archive file does not
yet exist it will be created. The files you want to add to the archive can
be given with ``wildcards'' (file selection pattern) in the \field{Files} or
in the file selection manager. That is, if you want to add all files with
the extension {\tt .C} you move the file selector box to the directory in
question, type {\tt *.C} and click at the \button{OK} button.

Since {\zoo} version 2.1 files can be stored using the high performance
compression, which leads to considerably smaller archives. However, high
performance compression is not used automatically when adding a file to an
archive. You have to select the {\zoo} modifier \field{h~~high performance
compression} if you want to use it.

If you specify files with the GEM file selector box you will always get a
full pathname with drive id and directory identification. However, in most
cases you do not want to store files with their full pathnames in the {\zoo}
archive. For example you have a directory {\tt LETTERS} somewhere deep down
in your folder path and now you want to save all those letters in a {\zoo}
archive. I suppose you only want to have the pure filenames of the letters
in your {\zoo} archive, say {\tt THOMAS.DOC, SUSAN.DOC,} and {\tt CINDY.DOC}
instead of their full filenames.

Well, {\Arcgsh} also thinks so. It tries to guess what you would like as the
working directory for {\zoo}. Why a working directory?  Well, as explained
above {\zoo} accesses files given without an absolute path relative to its
working directory. This is of course also true when {\bf adding} files to an
archive. In the above example {\Arcgsh} would set {\zoo}'s working directory
to the letters directory {\tt (...$\backslash$LETTERS)} assuming you have
selected {\tt ...$\backslash$LETTERS$\backslash$*.*} as files to be added.

How does {\Arcgsh} proceed to determine an appropriate working directory? It
looks at all those filenames that are given as full pathnames (with drive id
and path specification) and determines their common prefix. For instance the
files {\tt A:$\backslash$FOO$\backslash$FILE1,
A:$\backslash$FOO$\backslash$FILE2,} and {\tt
A:$\backslash$FOO$\backslash$BAR$\backslash$FILE1} have {\tt
A:$\backslash$FOO$\backslash$} as their common prefix. This common prefix is
chosen as the working directory for {\zoo}, and {\Arcgsh} hands the specified
files over to {\zoo} with their prefixes stripped off. In the example above
the files are stored as {\tt FILE1, FILE2,} and {\tt BAR$\backslash$FILE1.}

However, this mechanism is not always appropriate. Consider the case when we
want to archive all files in the directory {\tt
A:$\backslash$FOO$\backslash$BAR} but we want them to be stored {\bf with}
{\tt BAR} before the filename. We can achieve this by specifying the working
directory explicitly with the file selection handler: We set the working
directory to {\tt A:$\backslash$FOO$\backslash$} and specify {\tt
BAR$\backslash$*.*}.  {\bf Whenever the working directory is selected
explicitly by the user {\Arcgsh} will leave all selected filenames as they
are.}



\subsubsection{Adding complete file trees to a zoo archive}

A complete file system can be added to a {\zoo} archive by use of the
\field{//~~create dirs $|$ add complete dirs} modifier. This modifier is not
available in the original {\zoo} program but only in the Atari ST port. It
tells {\zoo} the following: If one of the selected files is a directory,
recursively\footnote{{\bf Recursively} means that all subdirectories are
added, all subsubdirectories contained in the subdirectories and so on.} add
all its files and subdirectories to the archive.

If the \button{//~~create dirs $|$ add complete dirs} option is not set
{\zoo} ignores directories.



\subsubsection{Zoo modifiers}

The behavior of {\zoo} commands can be influenced by the the use of {\bf
{\zoo} modifiers.} When you select any {\zoo} command button {\Arcgsh} will
display the modifiers that are available with this particular command on the
right hand side of the {\zoo} dialog box.

In principle you are free to choose any combination of modifiers.  However,
there are some cases where some modifiers are either mutually exclusive or
have to be specified either together or not at all.  {\Arcgsh} does not check
for those cases. It will leave this task to {\zoo}.

A special field in the \field{Zoo modifiers} box is the \field{Numbers}
field. You can insert any numeric parameter(s) to {\zoo} here.  This is
neccessary in connection with generation limits and corrupted archives.
Please refer to the {\zoo} reference manual!



\subsubsection{The TMPDIR field}

In the \field{TMPDIR} field you can specify a directory where {\zoo} should
create temporary files during packing.\footnote{It is committed to {\zoo} in
the environment variable TMPDIR.} This directory should be on a fast medium
like a RAM disk or a hard disk.



\subsection{Arc}\label{Arc}

{\Arcgsh} works together with {\arc} 6.02 although the really important
functions are also available if {\arc} 5.21 is used.

The {\arc} dialog box pops up when you select the \menu{Arc~...}\ menu item
from the \menu{File} menu. Its handling is similar to the handling of the
{\zoo} dialog box. In fact it is even easier. Therefore the instructions
given in this section do not go so much into detail as the section before.
If you are not able to understand anything read the instructions about the
{\zoo} archiver in section \ref{Zoo} (page \pageref{Zoo}).



\subsubsection{Extracting a whole arc archive file}

\begin{itemize}

\item Select the archive file to be extracted (extension {\tt .ARC}) into the
\field{Archive} field.

\item Click at the \button{Extract} button in the \field{Arc commands} field.

\item Optionally select one or more options from the \field{Arc options}
field.

\item Click at the \button{OK} button. Now {\tt ARC.TTP} is executed and
extracts the files into the same directory the archive file is in.

\end{itemize}



\subsubsection{Extracting particular files from an arc archive file}

If you do not want to extract {\bf all} files from an archive you have to
specify the names of the files you want to extract.

This can be done in the \field{Filename} field or in the file selection
handler. The latter will appear if you click at the \button{more~files...}
button.

Filenames may be given with wildcards. So it is possible to specify {\tt
*.C} as a filename which will lead to extraction of all files with the
extension {\tt .C}. It is not neccessary to specify all of them separately,
e.\,g.\ {\tt FOO.C, BAR.C, ...}



\subsubsection{Extracting from an arc file into another directory}

In addition to the above steps you have to specify the directory where the
extracted files should be created.

It can be given in the \field{Working directory} field in the file selection
handler. Another possibility is to prepend the names of the files to be
extracted with the full drive and directory specification. So it is
equivalent either to specify {\tt A:$\backslash$FOO$\backslash$BAR} as the
working directory and {\tt *.C} as files to be extracted or to specify {\tt
A:$\backslash$FOO$\backslash$BAR$\backslash$*.C} as files to be extracted.



\subsubsection{Adding files to an arc archive}

To add files to an {\arc} archive you have to select the \button{Add} command
button. If the {\arc} archive file does not yet exist it will be created. The
files you want to add to the archive can be given with
wildcards.

{\arc} always stores files {\bf without} drive or directory identification,
no matter what you have specified.



\subsubsection{Adding complete file trees to an arc archive}

Archiving of subdirectories is possible from {\arc} 6.02 on. If you select
the \button{Include subdirectories} option a {\bf whole} directory tree is
archived. The directory name must be specified like a normal filename. {\bf
Attention:} There is no chance to archive particular files from a
subdirectory. Similarly you can either extract the {\bf whole} subdirectory
tree from an archive file or nothing at all.



\subsubsection{The ARCTEMP field}

In the \field{ARCTEMP} field you can specify a directory where {\arc} should
create temporary files.\footnote{It is committed to {\arc} in the environment
variable ARCTEMP.} This directory should be on a fast medium like RAM disk or
hard disk.



\subsection{LHarc}\label{LHarc}

If you want to work with {\lharc} you should be aware of a lot of problems:

\begin{itemize}

\item The format of {\lharc} archive files\footnote{{\lharc} archives can be
recognized at their extension {\tt .LZH}.} is not unique. I have seen at
least three different {\lharc} archive formats. The situation is even worse
if you want to interchange {\lharc} archives with different computer
systems, e.\,g. computers running UNIX.

\item There are a lot of programs called {\tt LHARC.TTP} available. They
have different commands, different options, different command line formats
and the one you have might not be suitable for the {\lharc} archive you want
to extract.

\item The program is not the fastest.

\end{itemize}



\subsubsection{Predefined LHarc configurations}

If you want to use {\lharc}, the first thing to do is to configure
{\Arcgsh} to work together with that {\lharc}-Variant you want to use.
{\Arcgsh} has to know which {\lharc} commands and options are to be used to
achieve certain actions. For these parameters differ from {\lharc} to
{\lharc} {\Arcgsh} cannot provide suitable default values.

However, {\Arcgsh} knows about several {\lharc}s and has appropriate
configuration data already built in. On the right hand side of the {\lharc}
dialog box --- it is displayed when you select the menu entry \menu{LHarc
...}\ --- you can see those {\lharc}s {\Arcgsh} already knows. If ``your''
{\lharc} is among them, select the appropriate button, and {\Arcgsh} will
adopt itself to it. Using \menu{Save configuration} from the
\menu{Configuration} menu you can store the chosen configuration in
{\Arcgsh}s configurations file.

Depend on which {\lharc} configuration has been chosen only a part of all
commands and options can be selected. Those that are not to be selected are
greyed out.



\subsubsection{Establishing your own LHarc configuration}

If that {\lharc} you use refuses to work with one of the predefined
configuration things are a little more complicated. In this case you first
have to find out which {\lharc} commands cause which actions, e.\,g.\ an
``a'' as ``add'' to add files to an archive. These information should be
found in your {\lharc}s documentation. Alternativly you can try to call
{\lharc} without parameters, e.\,g.\ by {\Arcgsh}s function \menu{Other
program}. Many {\lharc}s print out a help text with all available commands
then.

Armed with a list of these commands and options you call \menu{LHarc~...} in
the \menu{File} menu an select \button{Edit}, and all texts in the fields
\field{LHarc commands} and \field{LHarc options} will be displayed in black.
For each command and option description you can specify a text now (in most
cases a single letter), which will be handed over to {\lharc} to perform the
requested action. For this purpose each entry has an editable text field.
You should delete the contents of such a text field if a certain command or
option is not available with the {\lharc} you use. The field \field{option
separator} has a special meaning: Upon parameter passing to {\lharc} this
string will be prepended to all specified options.

When you have made all settings you have to click at \button{Edit}. Now the
text fields are no longer editable and not available commands and options
are again greyed out.  Using \menu{Save configuration} from the
\menu{Configuration} menu you can store the chosen configuration in
{\Arcgsh}s configurations file.



\subsection{Shar}

Under the UNIX operating system there are so-called shell archives. They are
created by the program {\em shar\/} and usually contain pure text files.
For extraction the Bourne Shell, {\em /bin/sh,\/} is used.  This is of
course not possible on the Atari ST under TOS.  So I hacked together (not
more than that) a {\shar} program for the ST that also has an ``unshar''
component. For this I used two already existing versions of {\shar}:  one I
found on a local UNIX machine and one available for the Atari ST.  The
former one did not have an unshar component, and the latter did not have a
good directory support.  So I built my own one and adopted {\Arcgsh} to it.

This {\shar} version is not included in the {\Arcgsh} distribution but you
should be able to get it through the same channel you got {\Arcgsh}.  If you
already have a UNIX compatible {\shar} running on your ST you should at least
be able to {\bf create} {\shar} archives --- extracting is another matter.

The {\shar} dialog box pops up if you select the \menu{Shar ...}\ menu item
from the \menu{File} menu. You will see the following fields:

\begin{description}

\item[\field{Archive}:] The name of the {\shar} archive is specified here.
Default extension is {\tt .SH} but you may change it.

\item[\field{Create}, \field{extract}, \field{overwrite}:] Select whether you
want to {\bf create} a new {\shar} archive (this is the default) or {\bf
extract} an existing one.  {\bf Overwrite} is the same as {\bf extract} but
with overwriting already existing files.

\item[\field{Filename}:] Filenames to be included in the {\shar} archive may
be specified here or in the file selection handler.  Directory names may also
be given, but must not have a backslash (``{\tt $\backslash$}'') at the end.

\item[\field{more files ...}:] A click at this button invokes the file
selection handler. The specification of a working directory is essential
upon extraction.  Files without an absolute path are written to this
directory.

\item[\field{clear ...}:] Clears all entries in the file selection handler.

\item[\field{Shar options}:] {\shar} options may be selected here.  Refer to
the documentation of your {\shar}.

\end{description}



\subsection{Tar}\label{Tar}

Widely used in the UNIX world are also {\tar} archives, because {\tar} is a
part of each UNIX implementation. {\Tar} means ``{\bf t}ape {\bf ar}chive''
and is mostly used to store directory trees into a single file, e.\,g. on
magnetic tape. Data compression is not performed. However, you still have
the opportunity to compress the generated {\tar} file with the {\compress}
program (chapter \ref{Compress}, page \pageref{Compress}).

{\Arcgsh} works togehther with GNUTAR zusammen, a free {\tar} version, which
is also available for the ST.

Here a short description of the most important functions:



\subsubsection{List the contents of a tar archive}

\begin{enumerate}

\item Select \menu{Tar...} from the \menu{File} menu.

\item Enter the name of the {\tar} archive into the field \field{Archive}.

\item Select the command button \button{t~~list} from the \field{Tar
commands}.

\item Click at \button{OK}. {\Tar} shows the contents of the archive.

\end{enumerate}



\subsubsection{Extract from a tar archive}

\begin{enumerate}

\item Select \menu{Tar...} from the \menu{File} menu.

\item Enter the name of the {\tar} archive into the field \field{Archive}.

\item Select the command button \button{x~~extract} from the \field{Tar
commands}.

\item If needed, use the file selection manager (to be called by \button{more
files...}) to select a folder where the extracted files should be written
into. Otherwise they will be extracted into the same folder where the
archive is in.

\item If you do not want to extract the whole archive you can specify the
files to be extracted in the field \field{Filename} and/or by use of the
file selection manager.

\item Click at \button{OK}. {\Tar} is started now and extracts the archive.
Directory structures will be created as needed.

\end{enumerate}



\subsubsection{Add files to a tar archive}

\begin{enumerate}

\item Select \menu{Tar...} from the \menu{File} menu.

\item Enter the name of the {\tar} archive to be created into the field
\field{Archive}.

{\bf Attention:} {\Tar} always creates a new archive! If the specified files
already exists it will be overwritten!

\item Select the command button \button{c~~create} from the \field{Tar
commands}.

\item Specify the files to be added to the archive in the field
\field{Filename} and/or by use of the file selection manager. {\Tar} always
archives complete directory structures, i.\,e.\ if a folder is specified it
will be archived with all its files and subfolders.

\item Click at \button{OK}. {\Tar} will be started.

\end{enumerate}




\section{Compress}\label{Compress}

{\Arcgsh} workd together with the {\compress} 4.3 port by Dale Schumacher
(dal@syntel.uucp).

{\Compress} serves to compress or decompress single files. It does not pack
several files into an archive, but converts a single file into a compressed
representation and vice versa.

When compressing a file {\compress} appends the original file name with the
letter {\tt .Z}, if possible as an extension. Upon decompression the {\tt Z}
will be removed. The following examples may illustrate this;

\begin{quote}
\begin{tabular}{l@{ $\longrightarrow$ }l@{ $\longrightarrow$ }ll}
{\bf Originaldatei} & {\bf komprimiert} & {\bf dekomprimiert} & \\
\cline{1-3}
FOO	& FOO.Z   & FOO    & \\
FOO.C   & FOO.CZ  & FOO.C  & \\
FOO.CC  & FOO.CCZ & FOO.CC & \\
FOO.CCC & FOO.CCZ & FOO.CC & {\bf Attention!} \\
\end{tabular}
\end{quote}

Please note that upon compression of a file with an extension of three
characters the last character will be lost!

If {\compress} cannot compress a file the file itself --- and its name, too
--- will stay unchanged. Examples for files that cannot be compressed are
already compressed files or very small ones.



\subsection{Compressing a file}

\begin{enumerate}

\item Select \menu{Compress...} from the  \menu{File} menu.

\item Enter the name(s) of the files to be compressed into the field
\field{Filename} or use the file selection manager. Wildcards are possible.

\item See that the button \button{d~~decompress} in the field
\field{Compress options} is not selected. If needed, deselect it.

\item Click at \button{OK}; {\compress} will be started.

\end{enumerate}



\subsection{Decompressing a file}

\begin{enumerate}

\item Select \menu{Compress...} from the \menu{File} menu.

\item Enter the name(s) of the files to be decompressed into the field
\field{Filename} or use the file selection manager. Wildcards are possible.

\item Select the button \button{d~~decompress} in the field \field{Compress
options}.

\item Click at \button{OK}; {\compress} will be started.

\end{enumerate}




\section{Uud and uue}\label{Uud and uue}

The program pair {\uud} and {\uue} help to transfer arbitrary files through a
computer network. {\uue} takes a file as input and generates one or more
output files. The output files consist of printable characters only and can
be sent by electronic mail etc. The receiver of the ``uuencoded'' file(s)
makes use of {\uud} to generate the original file.

{\Arcgsh} works together with {\uud} 3.4 (25.11.1988) and {\uue} 3.1
(6.8.1987).



\subsection{Uud}

\begin{description}

\item[\field{File to be uudecoded}:] The file to be uudecoded should have an
extension {\tt .UUE} for a single file or {\tt .UAA} for the first one of a
sequence of files.

\item[\field{Source directory}, \field{Target directory}:] If these
directories are specified {\uud} reads the input file(s) from the source
directory and writes the generated file to the target directory.

\end{description}



\subsection{Uue}

Usually {\uue} generates one {\tt .UUE} file from the file to be uuencoded.
However, if the button \button{Generate multiple file output ...} is
selected {\uue} will create several output files with extensions {\tt .UAA,
.UAB, ..., .UZZ.} To change the maximum number of lines per file proceed as
follows:  First select the \button{Generate ...} button, then click at the
field with the max. number of lines per file and edit the number as you
like. The default of 500 lines seems appropriate since the individual output
files will be smaller than 32~KByte and most mailers can handle files of
that size.




\section{The user-defined pager}\label{The user-defined pager}

The user-defined pager allows you to look at a file without having to leave
{\Arcgsh}.  It is not a built-in function of {\Arcgsh}. Instead you are free
to choose a ``pager program'' which actually displays the file.  (I use and
recommend the public domain program {\tt LESS.TTP} by Moshe Braner.)

When you select the \menu{Show file ...}\ menu item from the \menu{File}
menu the GEM file selector box appears and asks you for the name of the file
to be shown. If the pager program has not yet been selected a dialog box
appears to let you do so (see description of the \menu{Configuration} menu).




\section{The user-defined editor}\label{The user-defined editor}

The user-defined editor allows you to edit a file without having to leave
\Arcgsh. It is not a built-in function of {\Arcgsh}. Instead you are free to
choose a text editor with which you actually edit the file.

When you select the \menu{Edit file ...}\ menu item from the \menu{File}
menu the GEM file selector box appears and asks you for the name of the file
to be edited. If the editor has not yet been selected a dialog box appears
to let you do so (see description of the \menu{Configuration} menu).




\section{Calling other programs}\label{Calling other programs}

Any other program than those mentioned above may be called by the menu item
\menu{Other program ...}.  In the dialog box you must enter the filename of
the program. Of course you can also enter program parameters, you can select
a working directory, and you can redirect standard input and standard
output.

Most programs take filenames as parameters. Therefore the GEM file selector
box will appear if you doubleclick at the \field{Parameters} field.  You
may e.\,g.\ first select a filename and then edit the field appropriately.

If no working directory is selected explicitly with the file selection
handler the directory of the dependent program is taken as the working
directory. {\bf Note:} If a GEM program needs a resource file it usually
tries to load it from the working directory and failes if the working
directory is not the directory the program itself is located.  Therefore no
working directory should be selected if such a program is to be started.




\section{The file selection handler}\label{The file selection handler}

The file selection handler is a dialog box (and some program logic behind
it) that allows you to specify a lot of filenames or other text to be given
to a dependent program as parameters. Additionally you can redirect standard
input and standard output, and you can choose the working directory of the
dependent program.

When the file selection handler appears you can see the following items:

\begin{description}

\item[Lines:] These lines are usually used to enter filenames. However, you
are free to enter any other text you want.

If you click at an empty line the GEM file selector will appear. You can now
navigate it to any directory and select a file from it. The name of the
selected file will be displayed with drive id and directory specification in
that line. If you like you can edit the line ``by hand''.

A filename too long to fit into the available space will be abbreviated at
the front by three dots so that you can see the last part of the filename
only. Abbreviated filenames are not editable. If you want to change the
contents of such a line you have to click at it. The GEM file selector will
appear again and you can select a file with a name short enough to fit into
the line. Then you can edit the line as you like.

The mechanisms described here also apply to the fields described below.

\item[\field{Standard input}:] Here you can specify a file the dependent
program should use as standard input.

\item[\field{Standard output}:] Here you can specify a file the dependent
program should use as standard output.

\item[\button{Append}, \button{Create}:] These buttons are useful when you
have selected a file for standard output. They specify whether the dependent
program should {\bf append} its output to an already existing file or if
the file used as standard output should be {\bf created} --- possibly
overwriting an already existing file.

\item[\field{Working directory}:] Here you can specify a working directory
for the dependent program.

\item[\button{OK}:] A click at this button leaves the file selection handler.

\item[\button{Cancel}:] This button also offers you a way to leave the file
selection handler. In contrast to the \button{OK} button all selections
and/or modifications you have made will be discarded.

\item[\button{Clear all}:] This button clears all text fields.

\end{description}




\section{Passing parameters to a dependend program}\label{Passing parameters
to a dependend program}

When you execute a program in many cases you have to hand over one or more
{\bf parameters.} They tell the program what to do. A good example are the
archivers supported by {\Arcgsh}: They take parameters that tell

\begin{itemize}

\item {\bf what} to do (e.\,g.\ add files to an archive, extract from an
archive) and

\item on {\bf what files} to operate (e.\,g.\ the archive, archive elements
or files).

\end{itemize}

All these parameters are handed over to the dependend program as a string of
charactersm, the so-called {\em command line}. However, there is a tight TOS
limitation that restricts the total parameter string length to 125
characters. If you specified more characters on the command line they are
gracelessly clipped off.

Of course there is a need to pass more than 125 characters to a program,
e.\,g.\ when an archiver is called with a lot of files that should be
processed. Consequently procedures have been worked out by several people to
achieve this.  These {\em extended parameter passing schemes} work as
follows: The calling program communicates the long parameter string to the
callee by use of an certain environment variable. The called program reads
its environment and checks for the variable that indicates an extended
parameter string. If it finds that variable it uses it. Otherwise it takes
its parameter from the command line.  It is clear that both caller and
callee must support the extended parameter passing scheme.

The most common extended parameters passing schemes are the {\em xArgv\/}
and the {\em ARGV\/} scheme. {\Arcgsh} supports both these schemes and can
therefore hand over more than 125 characters to a dependend program that
also supports the {\em xArgv\/} or {\em ARGV\/} parameter passing scheme.
The archivers {\arc} and {\zoo} are examples for such programs.

{\Arcgsh} supports {\em xArgv\/} and {\em ARGV\/} for registered users only.
On how to register see section \ref{The usual shareware plea} (page
\pageref{The usual shareware plea})!




\section{Automatic startup --- installing Arcgsh as a desktop application}

A very common situation is that you are working with the GEM desktop or
another shell browsing through your files. Now suppose you have an archive
file of any kind in one window and want to have a quick look at its contents
(or do something else with it). If it were a text file you could doubleclick
at it and view it with the desktop's built-in file viewer.

This is of course inappropriate for an archive file, because it is not a
text file. What you could do is open another window, navigate to the
directory where you have {\Arcgsh} installed, doubleclick at {\tt
ARCGSH.PRG}, select the appropriate archiver from the \menu{File} menu,
navigate the file selector box to the directory where your archive resides,
select the ``list'' command for the archiver and execute the latter.

However, {\Arcgsh} in cooperation with the GEM desktop offers you a much
simpler method which works under TOS~1.4 (``Rainbow TOS'') or higher TOS
versions\footnote{In order to make {\Arcgsh}'s autostart feature work under
pre-TOS~1.4 versions you must include the directory where {\Arcgsh} is
installed in the PATH environment variable.  However, this is not trivial
from the GEM desktop and can only be achieved with a dedicated program run
from the AUTO folder.  I think the free program GEMBOOT by Konrad Hahn does
so.}:  You can tell the GEM desktop to install {\Arcgsh} as a desktop
application.  After having done that all you need to do is doubleclicking at
the archive file. {\Arcgsh} will automatically start up and display the
right dialog box with the name of the archive file already filled in. Simply
select a command button --- e.\,g.\ ``list'' --- and click at \button{OK}.

You can do the same with a uuencoded file:  Doubleclicking on a file with
the extension {\tt .UUE} causes {\Arcgsh} to start and display the {\uud}
parameter box with the name of the uuencoded file filled in.

Here is a short explanation on how to install {\Arcgsh} as a desktop
application\footnote{The strings {\sf ``EXTRAS'', ``Install application'',}
and {\sf ``Save work''} cited in this paragraph are only roughly translated
from the corresponding strings of my German desktop. They may be different
on a real English desktop. They are surely different on other national
desktop versions. If in doubt consider your Atari ST User's Manual.}:

\begin{enumerate}

\item On the GEM desktop select the file {\tt ARCGSH.PRG}.

\item Move the mouse cursor to the \menu{EXTRAS} menu and select the
\menu{Install application} menu entry.

\item Type {\tt ZOO} into the \field{file type} field and click at the
\button{Install} button.

\item Select the \menu{Save work} menu entry from the \menu{EXTRAS} menu.
This causes the file {\tt DESKTOP.INF} to be written to the root directory
of your boot disk now and will make {\Arcgsh} permanently installed as a
desktop application.

\end{enumerate}

What you have done so far is installing {\Arcgsh} as an application for
{\zoo} archive files. Whenever you doubleclick at a file with extension {\tt
.ZOO} {\Arcgsh} will start up and display the {\zoo} dialog box. If you go
on and install {\Arcgsh} in the same way as described for the other
archivers and {\uud}, specifying the extensions {\tt .ARC, .LZH, .TAR}, and
{\tt .UUE} you will fail.  The reason is a limitation of the GEM desktop
which forgets about an earlier specified extension if a new one is given for
an installed application.

To circumvent this problem you have to edit the file {\tt DESKTOP.INF} with
a text editor after you have performed the above mentioned steps. Somewhere
in {\tt DESKTOP.INF} you will find a line like

\begin{quote}
{\tt \#G 03 04   C:$\backslash$BIN$\backslash$ARCGSH$\backslash$ARCGSH.PRG@ *.ZOO@}
\end{quote}

Here {\tt C:$\backslash$BIN$\backslash$ARCGSH$\backslash$ARCGSH.PRG} is the
full pathname of the {\Arcgsh} program. It may well be different on your
installation. The string {\tt *.ZOO} specifies the files for which
{\Arcgsh} should start up automatically.

Copy this line four times and change the string {\tt ZOO} within the copies
to {\tt ARC, LZH, TAR} and {\tt UUE,} resp. Now you should have

\begin{quote}
{\tt \#G 03 04   C:$\backslash$BIN$\backslash$ARCGSH$\backslash$ARCGSH.PRG@ *.ARC@}\\
{\tt \#G 03 04   C:$\backslash$BIN$\backslash$ARCGSH$\backslash$ARCGSH.PRG@ *.LZH@}\\
{\tt \#G 03 04   C:$\backslash$BIN$\backslash$ARCGSH$\backslash$ARCGSH.PRG@ *.TAR@}\\
{\tt \#G 03 04   C:$\backslash$BIN$\backslash$ARCGSH$\backslash$ARCGSH.PRG@ *.ZOO@}\\
{\tt \#G 03 04   C:$\backslash$BIN$\backslash$ARCGSH$\backslash$ARCGSH.PRG@ *.UUE@}
\end{quote}

Save {\tt DESKTOP.INF} to disk and reboot the system. After that {\Arcgsh}
automatically starts up for {\arc}, {\lharc}, {\tar} and {\zoo} archive
files and uuecoded files with the extension {\tt .UUE.}




\section{Limitations}

\begin{itemize}

\item {\lharc} is troublesome. Read section \ref{LHarc} (page \pageref{LHarc})
for details! Better use another archiver, e.\,g.\ {\zoo}.

\item A configuration file generated with {\Arcgsh} versions older than 3.0
cannot be used with this version. You have to establish a new version from
scratch.

\item A filename may not be longer than 119 characters. This is the filename
length the GEM desktop can handle. {\Arcgsh} may well bomb on longer
filenames. If you need {\Arcgsh} to support longer filenames please send me a
note!

\item Autostarting {\Arcgsh} under TOS versions older than TOS~1.4 only
works if the {\Arcgsh} directory is included in the PATH environment
variable.

\end{itemize}



\end{document}
