


               * ARCSYS THE ARCHIVER SHELL *

                       COPYRIGHT 1992

                    ALL RIGHTS RESERVED.



    ARCSys is a SHAREWARE program which has been created and
programmed  by  Graham  Phillips,   June  1992,  tested  and
documented by Peter Folge, specifically to run with the 'ARC
Engine  6.00',  which  was   created  by  System-Enhancement
Associates, Inc. in January 1989.

    With this package the following files are included:

        ARCSYS.PRG (the ARCSys shell)
        ARCSYS.RSC (resource file for ARCSYS.PRG)
        ARCSYS.TXT (present text file)

    If you distribute  this  program,  please  keep  all the
above files together. Thanks.


USING ARCSys

    ARCSys is a shell program designed to ease the use of an
arc engine such as  ARC  6.00.  It  runs  in  medium or high
resolution.

    Like any other shell it needs a fair amount of memory to
run. Really a 1 meg.  computer  is needed. Because the shell
and engine run together at the  same time about 600k of free
RAM is left to play about with. Just enough for a fair sized
RAM disk.

    Remember  that  when  you   are  Running  programs  from
archives more free memory will  be  needed  and only a small
RAM disk should be used.  Accessories  also take up valuable
memory so limit them to as few as possible or turn them off.

    NOTE:  PLEASE  EXPERIMENT   before   commencing  on  the
original data. You've been  warned.  This  goes  for all the
procedures listed in this program.


ARCSys COMMANDS/OPTIONS


THE COMMANDS ARE:


'Add to archive'    Always adds  the  folder  or  file. (Any
                    existing archive entries  with  the same
                    names will be overwritten.)


'Move to archive'   This adds the  folder  or  file and then
                    deletes the original.


    The next commands,  'Update'  and  'Freshen',  are a bit
complicated to understand at first, so two explanations have
been offered for each.

'Update in arc'     1) The file or  folder  is only added to
                    the archive if it does not exist already
                    and if it is  a  newer  version than the
                    one already present.

                    2) The file  or  folder  is added unless
                    it, or a  newer  version, already exists
                    in the archive.


'Freshen in arc'    1) This  is  similar  to  Update, except
                    that new folders or  files are not added
                    to the archive  only  updated.  In other
                    words freshen will update files within a
                    folder of an  archive  by replacing them
                    with new ones and deleting the old.

                    2) The file or  folder  is only added if
                    an older version  already  exists in the
                    archive (thus replacing it).


    Summary: Both 'Update' and  'Freshen'  look  at the date
and time stamp of the file and check if it has altered since
it was last archived. 'Update' looks  for the files on disk,
and adds  them  if  they  are  new  or  have  changed, while
'Freshen' looks in  the  archive,  and  tries  to update the
files which are already there.

    NOTE: a subdirectory  (folder)  can  only  be physically
altered within an archive  using  the 'Update' and 'Freshen'
commands. (With the other commands,  such as 'Add', 'Delete'
and 'Extract', the entire folder is affected.)


'Delete in arc'     Deletes a complete  file  or folder from
                    an archive.


'Extract from arc'  Extracts  a  file  or   folder  from  an
                    archive.


'Run from archive'  Any file with the  extension .APP, .PRG,
                    .TOS  or  .TTP  can   be  run  from  the
                    archive. The program is first extracted,
                    run and then deleted.


'Copy to std O/P'   Archives  may  be  examined  by  sending
                    their  data  directly  to  the  standard
                    output. This can  be  to  the  screen or
                    printer. In the  case  of  ARC 6.02ST it
                    sends data to the parallel printer port.


'List files in arc' Puts up on  screen  a  brief  list of an
                    archive's contents.


'Verbose listing'   Puts up a detailed  list of an archive's
                    contents. Displays folders,  file names,
                    original   length,    storage    method,
                    compacted  size  and  percentage,  date,
                    time and CRC.


'Test files in arc' This first extracts  the  file or folder
                    and  then  checks  that   all  the  file
                    headers are properly placed and that all
                    the data is in good shape.


'Convert to new'    This  is  used  to  convert  an  archive
                    entry,   taking   advantage   of   newer
                    compression    techniques.    This    is
                    desirable when a new  version  of ARC is
                    released.   Unfortunately   ARC   6.02ST
                    cannot use this command.


THE OPTIONS ARE:


'Move files to arc'

    The 'Add',  'Update',  and  'Freshen'  commands  may  be
modified by the 'Move' option. This  tells ARC to delete the
file from the source, in  much  the  same  way as the 'Move'
command itself.


'Include folders'

    This is the  new  method  incorporated  with ARC version
6.00.  This   allows   complete   directories   with   their
subdirectories (files and folders) to be used in an archive.


'Verbose mode'

    When used with any  command  that  creates a new archive
(e.g. 'Add' or 'Move'), it tells  ARC  to  add a note to the
archive saying which  version  of  ARC  created the archive.
This is then automatically updated every time the archive is
modified, and is displayed during a verbose listing.


'Retain backups'

    During an ARC operation, ARC  creates a new archive with
the same name, but  with  an  extension  "$$$". It will then
read from the original archive and write out the new archive
with any changes to the "$$$"  copy. When ARC is finished it
deletes the original and  renames  the  "$$$" archive to the
name of the original. This is the normal procedure.

    This means  that  if  anything  goes  wrong  during  the
copying process then the original archive is quite safe.

    However with 'Retain  Backups'  it  also  keeps a backup
copy of  the  unchanged  original  version  and  renames its
extension to '.BAK'.


'Suppress compression'

    This option  can  be  used  with  any  of  the following
commands: 'Add', 'Move', 'Update',  'Freshen' and 'Convert'.
It prevents any compression techniques from being used. This
is intended to allow you to add a  few files at a time to an
archive quickly, and then  later  convert the archive (using
the 'Convert to  new'  command)  to  compress  everything at
once. (Of course this won't work with ARC 6.02ST.)


'Suppress warnings'

    ARC prints three types  of messages: warnings, comments,
and errors.

    Warnings are messages about  likely  errors. For example
when a file  to  be  extracted  already  exists,  or when an
extracted file fails the  CRC  error  check. Warnings may be
suppressed by  use  of  this  function.  This  option should
rarely be used.

    Comments are informative messages,  such  as naming each
file as  it  is  added  to  the  archive.  Comments  may  be
suppressed by using this command.

    Errors are actual system  problems,  such as running out
of disk space. You  cannot  suppress  errors.  (Refer to the
'Clamp Screen' option in the configuration section.)


'Overwrite files'

    This is used  to  overwrite/replace  existing  files (on
disk) by extracting data from an archive and overwriting the
existing files. With this  option  disabled, ARC will prompt
you for every data file that already exists.


'Level 5 compatibility'

    This option  can  be  combined  with  any  command  that
changes an archive. It tells  ARC that the resulting archive
should be fully  compatible  with  ARC  version  5.  This is
necessary for creating an archive that is to be extracted on
another operating system where the  version of ARC available
for that system  does  not  yet  support  the  ARC version 6
extensions.

    The resulting archive will  not contain any directories,
comments, or any other  such  data  for non MS-DOS operating
systems.


'Hold screen'

    This function will freeze/hold the  screen at the end of
an archiving process. A  recommended  function  to have set.
See also the 'Clamp Screen' function in the config. section.


'Password Encryption'

    This is activated by clicking on the password box. It is
not a very sophisticated encryption method, but good  enough
for casual use.

    It is not wise to use different passwords for individual
files. Once forgotten, access will be lost for ever.

    Whenever you use password encryption, you will be warned
and given a chance to abort. Any spaces used in the password
will be removed.

    NOTE: It is possible to list the entries in an encrypted
archive using  the  "List"  and  "Verbose"  commands without
giving the password, but nothing else will work properly.


'Colour'

    Suitable alternative colours (in  medium resolution) may
be chosen by clicking on this  button.  They can be saved in
the configuration table. In  high  resolution, this function
toggles the pen and paper  colours  (i.e.  white on black to
black on white and vice versa).


'Use Accs'

    Any accessories that you have  loaded  may be called via
this function.


THE CONFIGURATION MENU:


    It  is  important  to  first   locate  the  ARC  engine.
Preferably ARC 6.02, but ARC 5.21  can  also be used (as can
any other versions!).  Click  on  'Select ARC engine'  to do
this.


Setting the Default paths:

    Select the Archive path  to  where  the archives will be
written, preferably onto a  RAM  disk  or  hard disk, before
transferring to floppy.

    Finally set the Data path, where  the data files will be
read from (or written to if extracting).

    In order to use the  default  paths, they must be turned
on (by selecting the 'Use default path' buttons). Otherwise,
ARCSys will simply  use  the  last  paths  used  in the file
selector boxes. (Useful in certain cases.)

    NOTE: setting the archive and  data  paths does not mean
that you are bound by  your  choices.  The paths merely tell
ARCSys where to open the file selector boxes.


    You can also set the default archive extension; that is,
the three characters  after  the  full  stop.  If  you don't
supply the extension when typing  in an archive name, ARCSys
will attach the default extension  for you. The extension is
normally "ARC" but you can choose what you like.


'Archive Prompt'

    This function supplies the name  of  the archive used by
the previous job when  asking  for  an  archive  in the file
selector box. This is useful  when  adding files in separate
batches or for listing an archive after adding to it.


'Buffer Screen'

    This is used to  speed  up  the  redrawing of the ARCSys
main  screen  after  using   accessories  and  running  ARC.
However, it uses approx. 32K  of  memory,  so  this can be a
problem if there is a shortage  of  RAM. In this case it can
easily be turned off.


'Bell'

    This makes ARCSys ring  a  bell  to  grab your attention
after each archiving job. This means you don't have to watch
the screen to see if ARC has finished its task.


'Clamp Screen'

    This modifies the 'Hold screen'  option in the main menu
so that ARCSys holds the  screen  instead of instructing the
ARC program to do it. You  can  then  press any key or mouse
button to get back to the main menu.

    NOTE: 'Hold screen' must also  be  activated for this to
work. This means  that  the  screen  is  held  even if error
messages are produced  by  the  ARC  program. (Normally, the
main menu would appear before you  had  a chance to read the
error message.)


'Save Configuration'

    Once ARCSys is  set  up  as  desired,  i.e.  most useful
options highlighted,  chosen  colours  set,  buffer  on/off,
location of  ARC  engine  and  default  paths  set  etc. the
configuration can be saved.  This  causes  an ARCSys config.
file to be created on disk.


EXTRA CONTROLS FOR ARC

    ARC can be paused  at  any  time  by pressing Control-S.
Pressing Control-Q  continues  the  ARC  operation.  You can
abort an ARC operation by  pressing  Control-C. Note that it
will finish processing the current file before aborting.


    A quick note on the two major variations of ARC:

                ______________ VERSION 5.21

    Version  5.21  uses  the   squeezed/squashed  method  of
compression which has the advantage of being able to compact
files more closely. ARCSys is able  to use this version, but
the 'Include folders' option is void.

                ______________ VERSION 6.00

    Version 6.00  is  an  overall  performance  upgrade. Its
operational  speed  has  been   greatly  improved  and  also
complete directories and folders can be added to an archive.
Unfortunately ARC  6.00  cannot  squeeze/squash  files, only
extract them.


                         SHAREWARE
                         

    ARCSys is  SHAREWARE.  If  you  use  this  program  (and
hopefully  enjoy  doing  so)  then   we   ask  for  a  small
contribution.  We  think   five   pounds   (Sterling)  is  a
reasonable sum.

    For  an  extra  three  pounds  we'll  send  you  a  disk
containing the GFA BASIC  source  code  in  ASCII format (so
that those without GFA BASIC can also study the program).

    Also included: lots  more  of  our  amazing programs and
their source codes to fill the disk.

    Please send donations to:

            Graham B Phillips
            6 Hertford Road
            Digswell
            WELWYN
            Herts
            AL6 0DE
            ENGLAND


    We  also  welcome  any   comments  and  suggestions  for
improvements to the  program  and  we  will  also answer any
queries  regarding  the  program,  but  please  remember  to
include a stamped, self-addressed envelope.

    Many thanks,
                                             Peter & Graham.


         ******************************************

                         DISCLAIMER
                         

    Although we  have  tested  this  product  thoroughly, we
cannot be held responsible for any damages whatsoever caused
to your system or for any  loss  of  data through the use of
this product. (Or any other product, come to that.)


         ******************************************


------------------------------------------------------------

          PROGRAMMER'S NOTES AND EXTRA INFORMATION
          

Background

    I wrote ARCSys because the two shells that came with ARC
v6.02ST couldn't  handle  folders.  Also,  this  shell  does
precisely what I want it to do, and nothing more. The colour
options are rather superfluous, but fun nevertheless.

    I  have  quite  a  bit   of   experience  of  GFA  BASIC
programming, originating with version  3.04,  but this is my
first attempt at programming with  resource files. There are
mixed opinions on  the  values  of  separate  .RSC  files. I
decided on a separate file because:

    a)  I don't know how  to  incorporate  the code into the
        main program (but I'm working on it)

    b)  resource files can be easily  edited - handy for the
        programmer or translator.

    I personally don't  mind  separate  .RSC  files;  I just
shove all the files on the  hard  disk and forget 'em, but I
suppose it can be a bit of a hassle for RAM disk users.

    ARCSys version 2.71 is the  first version to be released
in the  Public  Domain.  All  previous  versions  were  used
exclusively by myself  and  Pete.  This  is  the  latest and
greatest. About 100K of free  memory  is required to run it;
this  reduces  to  about  37K  when  running  ARC  or  using
accessories with the screen  buffer  off  and about 68K with
the buffer on. In practice  the  program shouldn't use 100K;
it includes a safety factor  to  ensure  that it doesn't run
out of memory. This cannot  prevent  ARC from running out of
memory, however. I'd like to check for this too, but I don't
know how much memory ARC needs to run satisfactorily.


    I added the colour option  for  a  laugh (albeit a short
one) after a suggestion  from  Peter. It randomizes hardware
colour registers 1 & 2  and  leaves  the text and background
colours alone, otherwise you could get some unreadable text.
In the  config.  menu  'Restore  Desktop  Colours'  sets the
colours back  to  what  they  were  before  ARCSys  was run;
'Restore ARCSys Colours' sets  them  to  the ARCSys defaults
(saved  in  ARCSYS.CFG);   'Restore   Desktop  colours  when
quitting' (a long  button  for  a  small  function) sets the
colours back to what they  were  before  ARCSys was run when
you quit ARCSys. Does that make sense?

    N.B. the latter button won't work if ARCSys was run from
NeoDesk (a thoroughly excellent GUI)  or similar shell which
remembers its  own  colours  and  sets  them  when  programs
terminate.


Default Paths

    There are certain rules regarding the paths as specified
in the config. menu. For the ARC engine, these are:

    1)  Attempt to set path, engine  & drive as specified in
        configuration.
    2)  If unsuccessful, attempt to  set  path and engine as
        specified in configuration but on current drive (the
        drive ARCSys was loaded from).
    3)  If unsuccessful, attempt to set engine to ARC.TTP in
        root directory of specified drive.
    4)  If specified drive  does  not  exist,  set engine to
        ARC.TTP on root directory of current drive.

    The ARCHIVES and DATA paths are set in a similar manner,
except that only paths are set, not specific files.

    IMPORTANT  NOTE:  the  program  assumes  that  the  File
Selector always  returns  a  valid  path.  Don't  try typing
anything funny into the directory line of the box!


    When you click on  'START'  the  program first checks to
see if the defined ARC  engine  actually  exists. If not, it
prompts you for it. Make sure you choose the correct file!

    After that,  ARCSys  prompts  you  for  an  archive file
(select one or type in a new one; when typing a file, if you
don't supply the extension, ARCSys  will append an extension
as specified in the config. menu).

    Finally, you are prompted  for  the  data files. You can
use the "?" and "*" wildcards  freely.  If you just click on
'OK'  (or  press  "Return")   without  selecting  or  typing
anything, the default "*.*" match  will be used, which means
"Select everything". N.B. with some  commands, such as 'List
files in arc',  the  term  "data  file"  doesn't really make
sense.  In  these  cases,  you  would  not  normally  select
anything, and so all entries  in  the archive would be acted
on. However, you can still use  wildcards as before to limit
the selection.


File Selectors and TOS

    ARCSys determines what TOS  version  it is running under
and modifies the way it  handles the File Selector slightly.
Specifically, if the TOS version  is less than 1.4/1.04 then
the prompt is placed above the box  on the menu bar line. In
other cases the prompt will appear  in the title line of the
File Selector. This is  important  because  the prompt won't
appear if you use a replacement  File Selector that does not
support the title line on an ST with TOS 1.4 (or above). The
only other problem that may  occur  is  if you have TOS less
than 1.4 and use a  replacement  File Selector that uses the
whole screen so that it  obscures  the prompt (although from
my knowledge of GEM this is not on).


Bells and Whistles

    The bell works by sending ASCII  7 to the screen. If you
use a fount  which  redefines  this  character  you  may get
problems. (I wouldn't know, though; I've never tried it.)

    If you turn off  'Buffer  Screen'  you  won't notice any
effect until you return from  using  accessories or when the
main screen  is  redrawn  after  invoking  ARC.TTP.  This is
because ARCSys  does  a  "garbage  collection"  before using
accessories or running ARC.TTP  which  sheds the 32000 bytes
for the screen, amongst other things. It's really noticeable
if you don't have something like Turbo ST or a blitter.


Other Bits

    ARCSys was developed on a  4M  STE using GFA BASIC v3.5.
The original program just used an intelligent menu bar which
was positively  boring,  so  I  decided  to  tackle resource
programming. The RSC interface was  written using the creaky
Digital Research RCS (which came  with GFA BASIC and without
a manual) but then  I  bought  HiSoft  WERCS  which a) had a
manual and b) was slicker.

    The program's been tested on 4M  520STE with TOS 1.62, a
1M 520STE with TOS 1.6 and  a  1/2M  520STFM with TOS 1.2. I
only checked it on the STFM to  see if it determined the TOS
version correctly; I didn't do any serious archiving. I used
the Moriarty Monulator to  see  how  it  looked in high res.
Unfortunately, the Monulator doesn't allow you to toggle the
screen colours under external  control  (it makes a flicker)
so I'm not absolutely  sure  that  it  works. The same thing
happens with the NeoDesk Control Panel, so here's hoping...


    Well,  that's  the  lot.  Keep   an   eye  out  for  the
forthcoming DiskFit!


Graham Phillips                                 26 June 1992



