@database IceArc.guide
@Width 80


@Node Main "IceArc - Main - (C) S.Gillibrand 1996 - Digital Design"

                                  @{b}@{fg shine}IceArc@{ub}@{fg text}
        Multi Format Programmable File Extraction System (phew :!)

                                Version 1.49
       (C) Copyright 1996 S.Gillibrand - Digital Design Productions

                                 FREEWARE

                      @{"        What Is IceArc?      " Link "WHATIS_ICEARC"}
                      @{"     System Requirements     " Link "REQUIR_ICEARC"}
                      @{"   How Do I Install IceArc?  " Link "INSTAL_ICEARC"}
                      @{"            Usage            " Link "USAGE!_ICEARC"}

                      @{"      BrainFile Editting     " Link "BRAIN!_ICEARC"}
                      @{"      RAM:IceArc.Results     " Link "RESULT_ICEARC"}

                      @{"          Known Bugs         " Link "BUGS!!_ICEARC"}
                      @{"            History          " Link "HISTOR_ICEARC"}

                      @{"  How To Contact The Author  " Link "AUTHOR_ICEARC"}
                      @{" What/Who Is Digital Design? " Link "DESIGN_ICEARC"}

@EndNode

@Node "WHATIS_ICEARC" "IceArc - What The Hell Is This? - (C) S.Gillibrand 1996 - Digital Design"

What Is @{b}@{fg shine}IceArc@{ub}@{fg text}?
+-------------+

@{b}@{fg shine}IceArc@{ub}@{fg text} is a MFPFES! (: multi-format programmable file extraction system)
:-), design by me because I was sick of all the other "Multi-Extractors" out
there - Like LX, DeCompress, UnArchive, Etc. Etc. - They all had quirks like
one didn't WORK at all, another was compiled arexx (urgh!) and LX (The best I
had seen) didn't allow a "<DEST>" parameter (because of ZIP/etc. not taking
that - But that's just a lame excuse IMHO). Not only is it configurable but
it does what I haven't seen ANY other multi-unarc'er do - It:

* Tests
* Deletes
* Adds
* Lists

Making @{b}@{fg shine}IceArc@{ub}@{fg text} truely versatile.

So here is @{b}@{fg shine}IceArc@{ub}@{fg text} - @{b}@{fg shine}IceArc@{ub}@{fg text} loads a brainfile every time it is executed, this
brainfile contains data on how to identify/handle/execute certain file formats
and thus making @{b}@{fg shine}IceArc@{ub}@{fg text} compatible with *ANY* archiver (in theory). This is
what makes @{b}@{fg shine}IceArc@{ub}@{fg text} so special :) It's great for:

o BBS's unarchiving files to be virus checked.
o Can also be adapted to view JPEGs upon recognition of such a file!
o It also works a treat with DOpus - Configure the "Drag-M-Drag" to use @{b}@{fg shine}IceArc@{ub}@{fg text}
  and it will unarchive ANYTHING from the <source> to the <destination>!
o Makes Mail Tossers life a dream - Unarchiving LZX/LHA/ZIP/ARJ/ARC/RAR for
  import.

Those are just a few of the uses @{b}@{fg shine}IceArc@{ub}@{fg text} can be put to - Now retrace (:)) and
take a look how to install @{b}@{fg shine}IceArc@{ub}@{fg text} and how to configure the BrainFile!

@EndNode

@Node "REQUIR_ICEARC" "ICEARC - System Requirements - (C) S.Gillibrand 1996 - Digital Design"

System Requirements
+-----------------+

1) An Amiga ;-)    <Why is it EVERY guide has this in - It's not funny ;0>

2) OS 2.0+

3) Archiver EXE's in search path. (e.g. C:LHA, C:LZX, C:ZIP, C:UNZIP).

4) Erm, hhuhuhuhuh - SHUTUP BEAVIS, right - erm, That's it :)

@EndNode

@Node "INSTAL_ICEARC" "IceArc - How To Install IceArc - (C) S.Gillibrand 1996 - Digital Design"

How Do I Install @{b}@{fg shine}IceArc@{ub}@{fg text}?
+---------------------+

Follow these simple steps OR use the provided C=ommodore Installer script.

1. Copy c/@{b}@{fg shine}IceArc@{ub}@{fg text} into your search path (reccomend "C:").
2. Copy s/@{b}@{fg shine}IceArc@{ub}@{fg text}.brain to "S:".
3. copy docs/@{b}@{fg shine}IceArc@{ub}@{fg text}.guide to your docs dir (reccomend "AMIGAGUIDE:").
4. Read how to edit the Brainfile.
5. EDIT IT! (If Needed :o))

Told yer it was simple ;-)

@EndNode

@Node "USAGE!_ICEARC" "IceArc - Usage - (C) S.Gillibrand 1996 - Digital Design"

Usage
+---+

Self explanatory really!

IceArc v1.4 - (c) S.Gillibrand 1996 - Digital Design Production - *FREEWARE*


Usage: 
 IceArc -<Operation(s)> <Source Archive> [Destination Path]

 _Operation_ being one of:
  -! - display archive format
  -x - unarchive <Source Archive> to [Destination]
  -a - add [Destination] to <Source Archive>
  -d - delete [Destination] from <Source Archive>
  -t - test <Source Archive>
  -l - list <Source Archive>
  -s - supress output of archiver executable to StdOut
  -c - auto-create directories from filenames when extracting

  -% - list known formats (read the docs for archive programming info)

  -b<brainfile path> - IceArc will use the specified brainfile if it exists
  -r<results path>   - IceArc will dump the results in the specified file

 Supplying no options will result in IceArc displaying the format and quitting
 If no Destination is specified then IceArc defaults to *Current Directory*

 Operations that require NO extra parameters may be stacked
 e.g. IceArc -xs sys:ta2.lzx ram:


Quotation Marks (") for files with spaces are supported. e.g. "Fire Starter.lha"

Wildcards for source filenames are now fully supported.

Upon recognition of a DMS File IceArc will attempt to read data from a file in
ENV: called "IceArc_FF" - inside this file there should exist a device name to
which IceArc will "UNDMS" the dms file to. FF0: is reccomended, RAD: or
(in the worst case senario) DF0: could be used also, after "UnDMSing" IceArc
will attempt to copy the contents of this device to the original directory
(if it is DOS) therefore making it possible to "UnDMS" to a directory!

See @{"IceArc Example Usages" Link "IAEXAM_ICEARC"} if you have brains!!!

Report any bugs to @{"Me" Link "AUTHOR_ICEARC"} please.

@EndNode

@Node "BUGS!!_ICEARC" "IceArc - Known Bugs - (C) S.Gillibrand 1996 - Digital Design"

Known Bugs
+--------+

None.

@EndNode

@Node "HISTOR_ICEARC" "IceArc - History - (C) S.Gillibrand 1996 - Digital Design"

History
+-----+

*Version 1.0
--------------------------------------------------------------------------------
Date       Details

28-Mar-96  First Public Release Of @{b}@{fg shine}IceArc@{ub}@{fg text}.
--------------------------------------------------------------------------------

*Version 1.1-1.2
--------------------------------------------------------------------------------
Date       Details

??-???-96  Internal Alpha/Betas of @{b}@{fg shine}IceArc@{ub}@{fg text}, limited distribution.
           Bug fixes/faster/code optimised.
--------------------------------------------------------------------------------

*Version 1.3[1][2]
--------------------------------------------------------------------------------
Date       Details

19-Apr-96  Default destination now changed to Current Directory instead of RAM:.
[0][1][2]  Destination path can now contain a trailing "/" or not, totally optional.
           If destination path doesn't exist, IceArc will attempt to create it.
           Now excepts source/destination with [Spaces] in them.
           Now auto-detects DMS Files and will unarchive them to a Fake Device
           as defined in ENV:IceArc_FF and then will attemp to copy file(s) to the
           original destination! :).
           Heavily optimised code some more :).
           Now when using "-a" if the SOURCE archive doesn't exist IceArc will
           list all known archives and ask you which flavour you'd like the NEW
           archive to be in! [Amazing!!].
           Now uses dynamic stack allocating code.
           Main structure now hits the memory direct instead of stack allocation,
           10000 bytes of stack should suffice for IceArc.
           Now accepts amigados wildcards for source filepath.
           Cleaned up the source and formatted printing some more.
           Some Auto-Variables now given their own register for greater speed.
           Now fully expands most path names for greater archiver compatibility.
           Amended typos in the GUIDE file :).
[3]        Fixed bug whereby when creating a NEW archive the input from the user
           was discarded and replaced with "0"!
           Oops :) That's what you get from using "auto-variables" - Wildcard
           file scanning now uses malloc() instead of the stack :).
           Creates a file called RAM:IceArc.Results which contains details on
           which files Failed/Successful. (See GUIDE).
           IceArc will use at maximum 60k of MEMF_ANY memory during operation, all
           of which will be freed when it is complete.
---------------------------------------------------------------------01-May-96--

*Version 1.4
--------------------------------------------------------------------------------
Date       Details

11-Jun-96  
 Improve   Improved %s & %d parsing speed & fixes to possible problems.
 Improve   Recoded command line options parsing in view to future expansion due
           to good response via e-mail (Thanx guys :)).
 Addition  Added .<suffix> line to brainfile (you'll need to edit your old one -
           not a hassle really) so IceArc can now unarchive from just the
           "bare" filename like lha/lzx/etc. can (e.g. ram:icearc14.lha can be
           extracted with "icearc -x ram:icearc14").
 Improve   Optimised a LOT of code as I learn better techniques :-). (L plates).
 BugFix    Fixed a double NULL definition error.
 BugFix    Fixed problem whereby if Env:Icearc_FF had a CR/LF at the end of it
           then IceArc wouldn't unarc the DMS and would even sometimes crash
           your system :///.
 Addition  Implemented "-b" command line option to specify a different brainfile
           to be loaded.
 BugFix    oOps, if IceArc couldn't open a file when ID'ing/Testing/Etc. it would
           report this but SKIP instead of carrying on to process the other file(s)
           found in the wildcard search. Thus if you "icearc -! ram:#?" then
           IceArc would quit with "Unable to open ram:icearc.results for input!".
 Addition  Implemented "-s" command line option which supresses the display from
           the archiver executable to STDOUT.
 Addition  Added "-c" command line option to auto-create directories from the
           filenames passed to it (e.g. icearc -x -c git.lha ram: would extract
           the archive to "Ram:Git.lha/").
 Change    Changed the format of the brainfile to, the first line contains a signature
           of "#!iCEARCBRAIn" so IceArc doesn't get fed crap and crash :) Also changed
           end of each archiver entry to include a "---".
 Change    Now uses expand_args() instead of getfnl() so now you can unarchive
           recursivley using things like "sys:#?/#?/#?" :) (Thus stack should be
           set to at least 8192 unless ya wearning a flame suit ;)).
 Improve   IceArc is now 15% faster at checking files :) <Happy Author>.
 Addition  Added Continue prompts to Usage and Brain File Display modes.
 Addition  IceArc will accept filenames preceeding with a "-" sign and will NOT
           treat it as an operation parameter (smart huh? :)).
 Improve   IceArc now requires 50k memory less than it used to, while running.
 Improve   Cleaned up some code, and possible bugs / error situations rectified.
--------------------------------------------------------------------------------

@EndNode

@Node "AUTHOR_ICEARC" "IceArc - How To Contact The Author - (C) S.Gillibrand 1996 - Digital Design"

How To Contact The Author
+-----------------------+

Please do contact me for @{"Bug Reports" Link "BUGS!!_ICEARC"} or @{"Improvement" Link "HISTOR_ICEARC"} ideas that you have.

You can contact me via the following methods:


BBS:
 Digital Dreams Amiga BBS UK - 44-1772-454995 - 24 Hours

NETMAIL:
 2:250/602.0

E-MAIL:
 psychoed@digitald.demon.co.uk
    sysop@digitald.demon.co.uk

SNAIL MAIL:
 Stuart Gillibrand,
 8, Thornton Drive,
 Farington Moss,
 Leyland,
 Preston,
 Lancashire.
 PR5 3QH
 ENGLAND


Don't hesitate to contact me no matter how trivial the matter.

@EndNode

@Node "DESIGN_ICEARC" "IceArc - The Famous Digital Design! - (C) S.Gillibrand 1996 - Digital Design"

What/Who is Digital Design
+------------------------+

Digital Design is a group of people who code all types of programmes for BBSs
around the world, TransAmiga, DLG, Xeno, ANY Basically.

It was founded by @{"Stuart Gillibrand" Link "AUTHOR_ICEARC"} in February 1995.


         President: Stuart Gillibrand - psychoed@digitald.demon.co.uk
         Vice President: Jamie Prince -  cosysop@digitald.demon.co.uk

Programmers:                                       ANSI Artists:
 Stuart Gillibrand                                  Stuart Gillibrand
 Jamie Prince                                       Jamie Prince


Documentation writers:                             Ideas:
 Stuart Gillibrand                                  Stuart Gillibrand
 Jamie Prince                                       Jamie Prince


If you would like to join Digital Design as a Programmer, Doc Writer, Artist
or Idea Conceptor (?!) then contact @{"ME" Link "AUTHOR_ICEARC"}.

We ONLY accept programming in the languages:

Arexx, C, E and ASM.

You will need to show us an example of your skill if you wish to join, which
both Jamie and I will look over before contacting you.

@EndNode

@Node "BRAIN!_ICEARC" "IceArc - How do I edit this BRAINFILE then ?!?! - (C) S.Gillibrand 1996 - Digital Design"

Ok here's what a segment of my example brainfile looks like:

--><----------------------------------------------------------------------------
LHA/LZH Archive                 <- Archive Label (ID)
.LHA                            <- Archive suffix
3                               <- Characters to skip before SIGnature is read
-lh                             <- The signature to look for (case sensitive!)
lha -X -F -M x %s %d <NIL:      <- The extract command (% commands listed below)
lha -X -F -M t %s <NIL:         <- The test command
lha -X -M v %s <NIL:            <- The list command
lha -X -F a %s %d <NIL:         <- The add command
lha -X -F d %s %d <NIL:         <- The delete command
--><----------------------------------------------------------------------------

[ % Parameters ]

%s = Source File
%d = Destination File

Now here's what @{b}@{fg shine}IceArc@{ub}@{fg text} would do if the brainfile contained that SINGLE entry
and it was given a file called "MadAsAHatter.lha" ([:) (File is an LHA archive)
 - Option given was "-x" - Destination was "ram:";

Skip first 3 characters:               &a-
Read next 3 and compare against "-lh"  -lh
-* match found *-
Get extract command line               lha -X -F -M x %s %d <NIL:
Parse command line                     lha -X -F -M x madasahatter.lha ram: <NIL:

Fairly simple if you let is sink in... The only difficulty in adding a new
archiver might possibly be finding a signature - Well the best way to find
a sig is as follows:-

1. Find 5-10 files of the SAME format (make sure you're certain).
2. Look for a common occurance (e.g. ZIP files have PK at the front of the file).
3. When you have found this occurance then you need to add it to the brainfile:
	Edit it with Ced/Ed/Ged/Etc. and add the following:

PK ZIP Archive                  <- Archive Label (ID)
.ZIP                            <- Archive suffix
0                               <- Characters to skip before SIGnature is read
PK                              <- The signature to look for (case sensitive!)
unzip %s <NIL:                  <- The extract command (% commands listed below)
unzip -t %s <NIL:               <- The test command
unzip -l %s <NIL:               <- The list command
zip %s %d <NIL:                 <- The add command
zip -d %s %d <NIL:              <- The delete command

And there you have it - You've just added a new file form to @{b}@{fg shine}IceArc@{ub}@{fg text}'s brain!

Specifying a single "#" on any COMMAND line defines that function as unavailable;
e.g.:

--><----------------------------------------------------------------------------
RAR File
.rar
0
Rar
unrar x %s <NIL:
unrar t %s <NIL:
unrar l %s <NIL:
#
#
--><----------------------------------------------------------------------------

(Above denoting that Adding/Deleting is not availble in RAR format).

[BTW if somone finds a RAR (Not UnRar I have that!) can you uuencode to me?!]

For further help contact @{"ME" Link "AUTHOR_ICEARC"}.

@EndNode

@Node "RESULT_ICEARC" "IceArc - What's IceArc.Results all about then ?! - (C) S.Gillibrand 1996 - Digital Design"

During the operation of IceArc, it will produce a file in RAM: called "IceArc.Results".
This file is for people who run IceArc in scripts / programmes / rexx macros and want
to be able to see what IceArc made of the file(s)/function(s) passed to it, like in
my "Upl" uploading software for TransAmiga which originally inspired IceArc!

The format is as follows:

--><----------------------------------------------------------------------------
<Filename Alone>      (prodigy.lzx)
<Fullpath + Filename> (bbs:bbsuploads/prodigy.lzx)
<Status>              (LZX Archive)
.. etc.
.. etc.
.. etc.
--><----------------------------------------------------------------------------

<Status> being one of:

!IOFAIL               - IceArc had problems with Input/Output on the file.
!NEWARC [x] - [y]     - A new archive was created by the user.
                        [x] being the archive NUMBER (As In IceArc.Brain)
                        [y] being the archive LABEL (As In IceArc.Brain)
!UNKNOWN_FORM         - IceArc's brainfile couldn't recognise this file.
<Archive Label>       - If IceArc was succesful then it will print out the
                        format's label (As In IceArc.Brain).

2 examples of a IceArc.Results file:

CLI:
(0)-16}-[Work:Comm/AmiTCP/usr/PsychOEd]> icearc -x a#? ram:

--><----------------------------------------------------------------------------
ansihijack.lha
Work:Comm/AmiTCP/usr/PsychOEd/ansihijack.lha
LHA/LZH Archive
ansihijack.readme
Work:Comm/AmiTCP/usr/PsychOEd/ansihijack.readme
!FORM_UNKNOWN
ansima11.lha
Work:Comm/AmiTCP/usr/PsychOEd/ansima11.lha
LHA/LZH Archive
ansima11.readme
Work:Comm/AmiTCP/usr/PsychOEd/ansima11.readme
!FORM_UNKNOWN
ansirender.lha
Work:Comm/AmiTCP/usr/PsychOEd/ansirender.lha
LHA/LZH Archive
ansirender.readme
Work:Comm/AmiTCP/usr/PsychOEd/ansirender.readme
!FORM_UNKNOWN
AmiFTP.prefs
Work:Comm/AmiTCP/usr/PsychOEd/AmiFTP.prefs
!FORM_UNKNOWN
AddPower95_4.lha
Work:Comm/AmiTCP/usr/PsychOEd/AddPower95_4.lha
LHA/LZH Archive
DoesntExist.lha
Work:Comm/AmiTCP/usr/PsychOEd/DoesntExist.lha
!IOFAIL
--><----------------------------------------------------------------------------

CLI:
(0)-16}-[Work:Comm/AmiTCP/usr/PsychOEd]> icearc -a tmp:example.lzx s:#?

--><----------------------------------------------------------------------------
example.lzx
tmp:example.lzx
!NEWARC 1 - LZX Archive
--><----------------------------------------------------------------------------

@EndNode

@Node "IAEXAM_ICEARC" "IceArc - Example usages of IceArc from the CLI..."

Example usages of IceArc from the CLI/Shell:

1> icearc -x home:aminet-cd-12.lha ram:
1> icearc home:aminet-cd-12.lha ram: -x

;- Would extract "Home:Aminet-Cd-12.lha" to "Ram:" if the format could be
   identified.

1> icearc -xs home:aminet-cd-12.lha ram:
1> icearc -x -s home:aminet-cd-12.lha ram:
1> icearc home:aminet-cd-12.lha ram: -x -s

;- Would extract "Home:Aminet-Cd-12.lha" to "Ram:" if the format could be
   identified, however the archiver's (LHA) output would not be displayed
   to STDOUT.

1> icearc -xc home:aminet-cd-12.lha ram:
1> icearc -x -c home:aminet-cd-12.lha ram:
1> icearc home:aminet-cd-12.lha ram: -xc

;- Would extract "Home:Aminet-Cd-12.lha" to "Ram:Aminet-cd-12.lha/" if the
   format could be identified.

1> icearc -d -rsys:icearc.feedback ram:flist200.lha #?.displayme
1> icearc -d ram:flist200.lha #?.displayme -rsys:icearc.feedback
1> icearc ram:flist200.lha #?.displayme -d -rsys:icearc.feedback

;- Would delete all occurences of "#?.displayme" from "ram:flist200.lha"
   and re-direct IceArc's result file to "SYS:icearc.feedback".

1> icearc -! -bsys:s/newbrain.ice work:misc/#?
1> icearc -! work:misc/#? -bsys:s/newbrain.ice

;- Would attempt to identify and display all files contained inside
   "work:Misc/" using the brainfile located at "Sys:s/newbrain.ice".

1> icearc -%

;- Would display the brainfile in a "human" readable context to STDOUT.


IceArc's Operation and Source/Destination handling routines are EXTREMELY
flexible thus you can't do much wrong, aslong as you follow the below
guidelines.

If the required operation requires a source and a destination then these
two fields must both be declared along side each other, for example:

1> icearc -x work:xfers/icearc14.lha ram:    ## Would work
1> icearc work:xfers/icearc14.lha -x ram:    ## Would NOT work
1> icearc work:xfers/icearc14.lha ram: -x    ## Would work

Operations that require no further parameters (e.g. !,x,a,d,t,l,s,c,%)
may be "chained" together on the command line. example:

1> icearc -xcs work:xfers/Upl11.lha df0:

   ## would work EXACTLY the same as ##

1> icearc -x -c -s work:xfers/Upl11.lha df0:



@EndNode