ARCHIVE 2.25 ============ Original by Andrew Black 1991 Modifications by J.G.Harston 1994-2003,2011 jgh@mdfs.net - http://mdfs.net/Apps/Archivers/Archiver Instructions for ARCHIVE ------------------------ ARCHIVE archives, dearchives and examines uncompressed Black, CJR, Zip and GetBack archives. It stores full Acorn file information, including file server metadata such as file modification dates. Extra features added to v1.8c and v2.00 onwards by J.G.Harston allow you to examine the contents of an archive, extract and run or display a single file from an archive, append to an archive, to read and write CJR archives as created by C.J.Richardson at 8-Bit Software, to read and write stored ZIP archives, Acorn GetBack archives, to create and extract self-extracting archives and to automatically create archives with !Where information files. Starting out ------------ When you run the program you will get a menu showing the recognised options, and a prompt waiting for a key. Pressing '?' will redisplay this menu while using the program. You can archive or de-archive files by pressing 'A', 'C' or 'D'. Archive files ------------- To proceed, do the following ... A. Press 'C' to create a new archive or 'A' to add to an existing archive. You will then be asked for a destination file name. This is the filename under which the archived data will be stored. It can be on a different drive to the source files. You are also asked whether you want a Black, CJR, GetBack or ZIP archive. Answer by pressing 'B', 'C', 'G' or 'Z'. B. The program will now ask you to enter the file names to archive rather like the example illustrated below ... Enter file to archive: BLOG or Enter file to archive: L.DATA It will repeat this for the amount of files you want to archive, reading them in as it goes. You stop by pressing Return on its own. For example to archive 3 files ... Enter file to archive: file1 Enter file to archive: file2 Enter file to archive: file3 Enter file to archive: You can specify that the name of the file in the archive should be different to the source file. This is done by appending the new name at the end following a comma. For example ... Enter file to archive: $.source.file1,file1 Will enter '$.source.file1', but in the archive it will be called 'file1'. You can also enter the name of a directory, and all the files in that directory and any subdirectories will be archived. *Commands can also be entered at this prompt. After pressing Return on its own to end the list, you should see the message 'Transfer successful'. You are then returned to the menu prompt. You can redisplay the menu by pressing '?'. Dearchive files --------------- The program will ask you for the filename of the archived file. Enter this and press . The program will then start to de-archive the archived file. It will display the approximate time it will take to work through the complete file. For example ... 129 seconds to de-archive complete file. Extracting L.DATA Extracting BLOG etc..... Now all you have to do is wait. While extracting files a percentage display of the progress so far is shown. When the computer has finished un-packing all the files it will print the message 'Transfer successful' if all went well. If any of the files need subdirectories, then they are created as it goes along. If saving to DFS, any long filenames are truncated to seven characters after any directory separators, ie 'E.LongName' would become 'E.LongNam'. Examine file ------------ This option lets you see what files are inside a archived file. Enter the filename, and the files and file addresses will be listed, along with the type of the archive, the total size of all the files in the archive, and an approximation to how long it will take to extract all the files. Any entries that are not stored files are shown with a '*' at the end of the line. Get single file --------------- It is possible to read a single entry from an archive with this option. Enter the filename and a list of the files inside is given. You are then asked for the name of the entry to read and asked how to read it. You can (E)xtract it and save it to disk, (D)ump it in hex or (T)ype it as plain text. If there is shadow memory or a Tube running, the Type option will run in MODE 3, otherwise MODE 7 is used. Self-extracting archives ------------------------ From version 2.13 ARCHIVE can run as part of a self-extracting archive. To do so, just CHAIN the archive, and the archived files will be extracted into the current directory. The current version uses a temporary file called '_tmp_' which Archive needs to be able to create in the current directory. A self-extracting archive can be created using the MakeSEA program. This feature has currently only been tested on BBC BASIC(65) and BBC BASIC(ARM). Command line options -------------------- On startup, a command line can be passed to ARCHIVE using CHAIN or if ARCHIVE has been *MCoded. The current options are: Archive () -quit If the -quit option is present, then on termination the is issued. If the command starts with a *, it is called as a *command, otherwise it is CHAINed. If a is passed, then it is examined as if with option E from the menu. Errors ------ When an error message is encounted ARCHIVE will close any open Exec file, and any files it has opened and then return to the menu prompt. If you try to open an unrecognised archive the message 'Not a Black/CJR/GetBack/ZIP archive' will be displayed. Probable errors --------------- Disc full - There is not enough space for the archiving or de-archiving of data. Disc read only - Take the write protect tab off and retry. File not found - Check spelling & Current Directory. Catalog full - You have tried to exceed the maximum number of files. Bad filename - Check Spelling - catalogue your disc if neccessary. Notes on ZIP files ------------------ ARCHIVE can extract and archive stored files in ZIP archives. ZIP is probably the most common archiving format in the world. Many ZIP archives compress the files within them, but currently ARCHIVE can only extract and store uncompressed files, known as stored files. There are various ways to create a ZIP file with stored data. Check the documentation for your ZIP creation program, looking for something like 'Options: No Compression' or 'Compression: Stored'. As an example, using PKWare's PKZip program, giving the following command: PKZIP -e0 -p -r name.zip dir\*.* will create a ZIP archive called name.zip containing stored copies of all the files in directory dir and all the contents of dir's subdirectories. Similarly, BBCZip defaults to uncompressed storage, so using: zip out/zip indir -r will create a ZIP archive call out/zip containing stored copies of all the files in indir, recursing into all its subdirectories. Compatability ------------- Archive has been tested and works on BBC B, Master, Compact, Archimedes, RISC OS, DFS, ADFS, HADFS, NFS, 6502Tube, Z80Tube, ARMTube. Technical Details ----------------- The format of a Black archive is as follows ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ A version 2 Black archive starts with a 'dummy' header to prevent earlier versions from extracting incorrectly: Read using INPUT# 0000 "" - ie, null string, ie 00, 00 0002 ( filelength-17 ) OR &FF000000 0007 dummy load% - set to zero 000C dummy exec% - set to zero 0011 rest of file starts here Repeated for each file: Read using INPUT#: name$ Filename len% length load% load address exec% execute address Version 2 archives then have: attr% file attributes Read using BGET: The bytes of the file Archive version before 2.10 will read a version 2 archive file as a single entry with the flag set to 'ignore this data'. Archive version 2.10 onwards can read version 1 archive files and version 2 archive files. The format of a CJR archive is as follows ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Read using INPUT#: 0000 ptr%(0) \ 0005 ptr%(1) \ 000A ptr%(2) } Pointers to entries : / 00FA ptr%(50)/ 00FF Each entry: Read using INPUT#: name$ filename load% load address exec% execution address len% file length attr% file attributes Read using BGET: The bytes of the file If a pointer is zero, it doesn't point to anything. Usually, the files run straight after each other. Current versions of Archive cannot cope with null pointers in the middle of the pointer list. With Black and CJR archives the bottom three bytes of len% is the actual data length occupied within the archive, even if this data expands to form a larger file. The top byte of len% is a flag. Current meanings are as follows: &00 File <>&00 Not a file &FF Ignore this data Future versions will use this flag to indicate actual file compression methods. The format of an Acorn GetBack archive is as follows ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Repeated for each file: n bytes : filename, 1 byte : filetype - 1=file, 2=directory 1 byte : disk number - starts at 1 4 bytes : load address 4 bytes : exec address 4 bytes : length - should be ignored if filetype=2 1 byte : access byte 2 bytes : modification date in NetFS format 2 bytes : modification time hh, mm (no seconds) length bytes of file data Stored filenames are the full path of the entry, often with an absolute directory reference, eg "$.CAVE", "$.CAVE.!BOOT". If the filename starts with '.', the initial '.' is skipped. Entries can be in any order, but will tend to be in the order that they were encounted when adding them to the archive. Format of a ZIP archive ~~~~~~~~~~~~~~~~~~~~~~~ The format of a ZIP archive can be found in separate documents. One such document is http://mdfs.net/Docs/Comp/FileFormats/Zip. Version History --------------- 24-Jun-2014 2.25 Uses external suffix file for filename extensions. 26-Aug-2012 2.24 Translates attributes to/from DFS. 11-Jun-2011 2.23 Speeded up CRC calculation. 24-Nov-2002 2.22 Creates GetBack archives. 23-Nov-2002 2.21 Extracts from GetBack archives, sets modification date on extracted directories. 15-Jan-2002 2.20 Better file extension handling, inserted filename translated in ZIP files. 27-Dec-2001 2.19 Bug in file closure on errors fixed. Self-extraction function migrated to RunDeArc. Divide by zero with zero- length files fixed. Percent display on manual CRC correct. 22-Nov-1999 2.18 Truncates long leafnames on extracting. Names in archives can be different to source names. 18-Nov-1999 2.17 OPENOUT/CLOSE/OPENUP adds a BPUT to fix allocation problems with zero-length file. X%/Y% restored when doing a directory. Manually calculates CRCs when not on 6502. 02-Oct-1999 2.16 Long ZIP filenames truncated to 10 characters on extraction, short extensions extended when archiving. ZIP creation works on all CPUs. 29-Sep-1999 2.15 Writes stored ZIP files. Can't yet extend ZIPs, and ZIP creation only supported on 6502 cpus. Slight tweek to get around OPENOUT/CLOSE/OPENUP problems. 21-Sep-1999 2.14 Errors close any open Exec file. Stored ZIP archives can be extracted. Preliminary code to create ZIP archives. Files filetyped to &DDC. 12-Dec-1998 2.13 Can run as part of a self-extracting archive, with program MakeSEA to create a self-extracting archive. Buffer no longer overflows with long files. Displays % count during file transfer. Understands !Where files, so ',' in filenames not allowed. |comments allowed at File: prompt when archiving. 12-Jul-1998 2.12 Uses newer command line passing properly. Creates CJR archives compatible with earlier Arch_De programs. 10-Jun-1998 2.11 Unset variable in Create CJR fixed. 28-Apr-1998 2.10 Black archives created with attributes saved. Examine gives an extraction time estimate. Some general internal tidying. 24-Sep-1997 2.02 Attributes set on files extracted from a CJR archive. ??-???-1997 2.01 Small tidying up, and parameter passing allowed. ??-???-1996 2.00 Public release version. ??-???-1996 1.95 Create and append given two menu entries. ??-???-1995 1.92 Better checking on adding to archives. ??-???-1995 1.90 Reads and writes CJR archives, examine single files from inside an archive, top byte of len% used as flag, subdirectories created where neccessary, JGH credit put on screen title. Error handling on file access tidied up to avoid CLOSE#0 fudge. 'Archive' in menu instead of 'Compress'. This version released internally to 8BS for testing. ??-???-1994 1.8c Small tidying-up fixes. Checks whether a file is actually an archive. Truncated long filenames when saving to DFS. ??-???-1993 1.8b Filing-system independance, menu, examine, *commmand and exit options added. Compress can take directories and *commands. ??-???-1993 1.8a First JGH modification using OSGBPB to improve speed ??-???-1991 1.8 Andrew Black's version. File read/write used BGET/BPUT and so very slow. No menu, various options forced onto the user. Forced the user to use DFS. Possible future improvements ---------------------------- * De-archiving to prompt for a destination directory. * More command line options.