






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

          *                                                          *

          *                          Beebug                          *

          *                                                          *

          *                    A R C H I M E D E S                   *

          *                                                          *

          *                AA      RRRRRRRR      CCCCCC              *

          *              AA  AA    RR      RR  CC      CC            *

          *            AA      AA  RR      RR  CC                    *

          *            AAAAAAAAAA  RRRRRRRR    CC                    *

          *            AA      AA  RR  RR      CC                    *

          *            AA      AA  RR    RR    CC      CC            *

          *            AA      AA  RR      RR    CCCCCC              *

          *                                                          *

          *                                                          *

          *                     by David Pilling                     *

          *                                                          *

          *                                                          *

          *              This program is Public Domain               *

          *                                                          *

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








*********************************************************************************                              ARC Version Numbers                             **                              -------------------                             **                                                                              ** Version 1.0 - 29/06/88       Initial release                                 ** Version 1.1 - 01/09/88       PKARC compatibility added                       ** Version 1.2 - 17/10/88       Network compatible version                      **                                                                              **                                                                              **                                                                              **                                                                              **                                                                              **                                                                              **                                                                              **                                                                              **                                                                              **                                                                              **                                                                              **                                                                              **                                                                              **                                                                              **                                                                              **                                                                              *********************************************************************************Archimedes ARC                                                          Page 2




                                  Contents

                                  --------



                         (1) Introduction

                         (2) How to use ARC

                         (3) ARC commands

                         (4) Archimedes ARC file format

                         (5) ARC support




1. Introduction

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

ARC is the Archimedes archive utility. An archive is a file in which many 

smaller files are stored. You may, using the ARC utility, create archives and 

add files to them (ARC'ing a file) or remove files (de-ARC'ing). One of the 

features of ARC, is that files are stored in a highly compressed form; thus 

saving disc space and allowing more rapid transfer of files by modem. However, 

probably the most useful feature of an archive is that like sub-directories 

in the ADFS, it makes keeping track of files when transferring them from one 

machine to another, much simpler.


Archives have a long history going back to UNIX and CP/M. An example of an 

archive with no compression is the UNIX shar format. Whilst on CP/M archive 

utilities which used data compression include squeeze, LUE and LBR. Perhaps 

the most well known archive format and utility is the System Enhancements 

Associates (SEA) ARC for the IBM PC which was based on many of these earlier 

programs. This has now been transferred to the Atari ST and Amiga micros. In 

addition, other more advanced versions of it have appeared on the PC like 

PKARC by Phil Katz. Beebug Archimedes ARC is fully compatible with SEA's ARC 

program. Using it, you can successfully unpack PC archives on your Archimedes, 

as well as create PC format archives. In addition, you can use a special 

Archimedes format archive which while not compatible with the PC, preserves 

Archimedes file attributes like load and exec addresses.


If you dial up your local bulletin board, you will see many ARC files (they 

are usually identified by the suffix .ARC). Using ARC, you will be able to 

transfer the files in these to your Archimedes. Obviously, you cannot use 

executable PC programs, but there are many text and data files which you may 

want to examine (such as documentation, C source files, screen images etc.).


Do not get the impression from the above, that the data compression aspect of 

ARC is just a side effect. Frequently, you may achieve a space saving of upto 

90%. Just how much space you save, depends on the type of file being ARC'd. 

Text files usually compress well. Whilst PC executable files rarely compress 

by much, Archimedes executables seem to show good savings in space (often 

owing to Acorn's way of handling arrays and because of the high redundancy in

ARM code).

Archimedes ARC                                                          Page 3




2. How to use ARC

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

Archimedes ARC consists of two files: the program ARC, and ARC_DOC containing 

this text. You use ARC by typing *arc followed by a number of parameters. If 

you type *arc on its own without parameters, a page of help information is 

displayed. For example:



    *arc


    Archimedes ARC - Archive utility

    Usage: ARC {amufdxeplt}[bswnoiq][g<password>] <archive> [<filename> . . .]

    Where:   a   = add files to archive

             m   = move files to archive

             u   = update files in archive

             f   = freshen files in archive

             d   = delete files from archive

             x,e = extract files from archive

             p   = print file to screen

             l   = listing of files in archive

             t   = test archive integrity

             b   = retain backup copy of archive

             s   = suppress compression (store only)

             w   = suppress warning messages

             n   = suppress notes and comments

             o   = overwrite existing files when extracting

             i   = Use IBM PC Archive format

             q   = Use PKARC style squashing

             g   = Encrypt/decrypt archive entry


    Written for the Archimedes by David Pilling

    Put in the Public Domain by BEEBUG V1.1 September 1988



Although the syntax of the ARC program may look a little frightening at first, 

it is really quite straightforward. Typically you will almost always use just 

a few of these options. The letters which appear after 'ARC', split into two 

groups; commands amufdxeplt and options bswnoiq and g. In general, you should 

have just one command letter and as many options as you need. The next section 

looks at the commands and options.

Archimedes ARC                                                          Page 4




3. ARC commands

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



a   = add files to archive


      This command is used to add files to an archive. If the archive does not 

      exist, it is automatically created. An example of this command is:


          *arc a utils_arc util1 util2 util3 util4


      This adds the files util1, util2 etc. to the archive utils_arc. You can 

      use wildcards in this command as follows:


          *arc a my_arc b* 


      This will add all files whose names begin with 'b' to the archive. You 

      can use any legal filename for the name of the archive, but we recommend 

      that you add the suffix '_arc' to the end of the name. This will help 

      you identify ARC files. In addition, ARC files can also be identified by 

      their filetype, which is set to &DDC (Acorn approved filetype).



m   = move files to archive


      This command is like 'a' except that the files are deleted from the 

      local filing system as they are added to the archive file.



u   = update files in archive


      This only adds files to the archive if the versions on disc have a more 

      recent date stamp, or if they are not already in the archive. For 

      example:


          *arc u my_arc


      will update all files in the current directory that have been created or 

      changed since they were last archived.



f   = freshen files in archive


      This is like the 'a' command, except that files are only added if they 

      already exist in the archive with an earlier date stamp.



d   = delete files from archive


      This command allows you to delete files from an archive. For example:


          *arc d my_arc bob


      will remove the file bob from the archive file.

Archimedes ARC                                                          Page 5




x,e = extract files from archive


      These two commands, remove files from an archive and create them in a 

      usable form on your disc. For example;


          *arc x my_arc util1


      recreates the file 'util1' from the archive. Notice that 'util1' remains 

      part of the archive. If you want to extract all the files, simply type:


          *arc x my_arc



p   = print file to screen


      This is very similar to 'x' and 'e' except that the file is printed out 

      on the screen, instead of being sent to the filing system.



l   = listing of files in archive


      This very useful command shows you the contents of an archive along with 

      much useful information. For example, to see the contents of the archive 

      called 'my_arc', type:


          *arc l my_arc


      You can, of course, specify individual files or groups of files using 

      wildcards. For example:


          *arc l my_arc pr*


      The information displayed gives the original length of the file, 

      and how long it is in its compressed form. The time and date stamps for 

      the file and information on which form of data compression has been used 

      to store the file. You will notice that this is preceded by either 'PC' 

      or 'ARC', which indicates whether the file is stored in PC or Archimedes 

      format. 



t   = test archive integrity


      A CRC (Cyclic Redundancy Check) is kept for each file added to the 

      archive, this allows ARC to tell you if a file has been corrupted. This 

      can happen when you are transferring files between different computers. 

      The 't' command unpacks all of the archive entries (without saving them 

      anywhere), and checks the CRC for each file against the recorded value. 

      It reports back to you any damage to the archive. For example, to test 

      that the archive 'my_arc' has been recieved correctly, type:


          *arc t my_arc

Archimedes ARC                                                          Page 6




b   = retain backup copy of archive


      When you add a file to an archive, the original archive is renamed to 

      B_oldname. Normally, this is deleted after the file has been succesfully 

      added. By using the 'b' option, you can keep a copy of the original 

      archive. For example, if you wanted to add the file 'program' to the

      archive 'my_arc', but want to keep a backup copy of the archive, 

      then type:


          *arc ab my_arc program


      The backup archive is called 'b_my_arc'.



s   = suppress compression (store only)


      This allows you to add files to the archive without compressing them.



w   = suppress warning messages


      This option prevents warning messages being printed.



n   = suppress notes and comments


      This option suppresses notes and comments.



o   = overwrite existing files when extracting


      When you extract a file, it may be that a file with the same name 

      already exists. Normally, you will be prompted to overwrite the file. If 

      you then select N, you will be prompted for permission to rename the 

      file. If you then select Y, ARC will pick a sensible name, but if you 

      select N, ARC will continue to the next file to be extracted. The 'o' 

      option allows you to prevent all prompting, and just overwrite existing 

      files. For example:


          *arc xo my_arc



i   = Use IBM PC Archive format


      When you add a file to an archive, ARC assumes that you want the file to 

      be stored with its load and exec addresses and attributes. However, if 

      you want to give an archive to a friend with a PC, you should store the 

      files in PC format by adding the 'i' option to the command line. For 

      example, to add a PC file to an archive, type:


          *arc ai my_arc PCprog

Archimedes ARC                                                          Page 7

q   = Use PKARC style squashing


      Squashing is a variation on LZW coding used by the fairly popular PC

      program PKARC. By adding this option, you make ARC use squashing instead

      of crunching. You should consider that squashing will not always be

      more efficient than crunching and often will produce only small gains. 

      However, there are far more copies of ARC than PKARC, and these will not

      be able to unpack squashed archives. ARC from version 1.1, can unpack

      IBMPC archives made using PKARC and it will do this whether you set the

      q flag or not.



g   = Encrypt/decrypt archive entry


      The 'g' (garble) option allows you to give a password which is used to 

      encrypt files stored in the archive. The data compression normally 

      applied will make files unreadable using *TYPE or *DUMP, this lets only 

      people who know the password extract them from the archive. For example, 

      if you wish to add 'newfile' to the archive 'my_arc', and encrypt it 

      using the password 'beebug', type:


          *arc agbeebug my_arc newfile


      When you want to extract the file again, you should type:


          *arc xgbeebug my_arc newfile


      The password can be any length, and is not case sensitive. You can if 

      you wish use different passwords for each file in an archive, but we 

      advise against it. If you should forget or mistype your password, it is 

      unlikely that you will ever recover the file.

Archimedes ARC                                                          Page 8




4. Archive file format

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

An Archive, is a binary file consisting of archive markers, archive headers 

and file data. All archives are preceded by an archive marker. This is a 

single byte of value 27.


An archive header, consists of several bytes.


byte  1      Header version number. This tells you how the file data is stored 

             and how many bytes there are in the header. The header version 

             numbers for the PC, are detailed below. An Archimedes header 

             version number is identical to the corresponding PC number except 

             it has bit 7 set.


bytes 2-15   Filename


bytes 16-19  Compressed file length


bytes 20,21  File date stamp


bytes 22,23  File time stamp


bytes 24,25  CRC for the file


bytes 26-29  If the header type is greater than 1, these hold the original 

             file length otherwise they are not present.


bytes 30-33  If bit 7 of the header version number is set, these bytes hold 

             the Archimedes load address for the file otherwise they are not 

             present. 


bytes 34-37  If bit 7 of the header version number is set, these bytes hold 

             the Archimedes exec address for the file otherwise they are not 

             present.


bytes 38-41  If bit 7 of the header version number is set, these bytes hold 

             the Archimedes file attributes otherwise they are not present.


The archive header, is followed by the file data.


The file data is followed by another archive marker


The archive finishes with an archive marker followed by a zero byte.


The time and date fields are always filled in. If the file has a load and exec 

address, these are the time and date when the file was added to the archive 

otherwise, they are derived from the Archimedes datestamp. In all extract 

operations on Archimedes format archives, the contents of the load and exec 

fields take precedence.


PC and ARC formats may be mixed in one archive for use on the Archimedes. 

Archimedes ARC                                                          Page 9




PC ARC Header version numbers:


       1 = Old style, no compression

       2 = New style, no compression

       3 = Compression of repeated characters only

       4 = Compression of repeated characters plus Huffman Squeezing

       5 = Lempel-Zev packing of repeated strings (old style)

       6 = Lempel-Zev packing of repeated strings (new style)

       7 = Lempel-Zev Welch packing with improved hash function

       8 = Dynamic Lempel-Zev packing with adaptive reset

       9 = PKARC style squashing


The time and date stamps are two byte values from which the time in years 

etc., can be found as follows;


       year   = (date >> 9) & 0x7f;   

       month  = (date >> 5) & 0x0f;

       day    = date & 0x1f;


       hour   = (time >> 11) & 0x1f;  

       minute = (time >> 5)  & 0x3f;

       second = (time & 0x1f) * 2;


Where years are offset from 1980, months begin with 1=January.

Archimedes ARC                                                          Page 10




5. ARC support

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

Please send any comments or suggestions for ARC to the address below. In 

addition, if you would like details of the latest version of ARC and how to 

get hold of a copy, please contact:


    Software Manager

    Beebug Ltd.

    Dolphin Place,

    Holywell Hill,

    St. Albans,

    Herts.

    AL1 1EX


    Tel. (0727) 40303