First a list of all commands and functions that are implementated in this
beta-version 0.5 of MTZIP.DLL. Before you may use this software, you must
read the ReadMe.TXT file included in this Zip-File. Then I will explain the
basics of the use of MTZIP.DLL and finally a list of futures that will be
included in the first non-beta-release.

Mark Toten


COMMANDS
--------
MTZIP MESSAGES,ON                      Show all messages
MTZIP MESSAGES,OFF                     Show no messages
MTZIP MESSAGES,ERRORSONLY              Show errors only
MTZIP ADD,BUFFER,<FileName>            Add a file to the buffer
MTZIP CLEAR,BUFFER                     Clear the buffer
MTZIP DELETE,BUFFER,i                  Delete item i from the buffer
MTZIP CREATE,ZIPFILE,<FileName>        Create a new zipfile
MTZIP LOAD,ZIPFILE,<FileName>          Load an existing zipfile
MTZIP LOAD,BUFFER,<FileName>           Load a list of filenames into the buffer (not tested!)
MTZIP PROCESS,ADD                      Add files in buffer to zipfile
MTZIP PROCESS,DELETE                   Delete files in buffer from zipfile
MTZIP PROCESS,EXTRACT                  Extract files in buffer from zipfile

FUNCTIONS
---------
@MTZIP(COUNT,ZIPFILE)                  Returns the number of files in the zipfile
@MTZIP(COUNT,BUFFER)                   Returns the number of files in the buffer
@MTZIP(SPANNING)                       Returns TRUE if the file is spanned, FALSE if not
@MTZIP(SFXOFFSET)                      Returns the size of the file that is taken by SFX Header in bytes
@MTZIP(SUCCESS)                        Returns the number of files of the buffer that have been processed successfully
@MTZIP(BUFFERSIZE)                     Returns the number of bytes of all files in the buffer
@MTZIP(COMMENT)                        Returns the comment (if present) that is enclosed in the zip-file
@MTZIP(FILENAME)                       Returns the filename of the zipfile that is currently being worked with
@MTZIP(FILESIZE)                       Returns the size of the zipfile (equal to @FILE(%%File,Z) ) in bytes
@MTZIP(ZIPFILESIZE)                    Returns the actual size of the zipfile (total filesize - SFX Header) in bytes
@MTZIP(ZIPFILE,i,COMPSIZE)             Returns the compressed size of file i (item in list) in the zipfile
@MTZIP(ZIPFILE,i,UNCOMPSIZE)           Returns the uncompressed size of file i (item in list) in the zipfile
@MTZIP(ZIPFILE,i,RATIO)                Returns the compression ratio of file i (item in list) with two decimals
@MTZIP(ZIPFILE,i)                      Returns the filename of file i (item in list)
@MTZIP(ERRORCODE)                      Returns the last errorcode

Possible errorcodes are:
-5 Password error
-4 All further passwords cancelled
-3 Password cancelled
-1 File not found
 0 No error
 2 Unexpected end of zip file
 3 Zip file structure invalid
 4 Out of memory
 5 Internal logic error
 9 Aborted by user
10 Temporary file failure
11 Error reading a file
12 Nothing to do!
13 Missing or empty zip file
14 Error writing to a file
15 Error creating file
16 Bad zip options specified
18 File not found or no read permission

HowTo Use MTzip.DLL
-------------------
First I recommend you not to turn off the messages. It will give you an easy
indication on what the DLL is working on. Of course, if you want to use MTzip.DLL
in an application to be released you can use MTZIP MESSAGES,OFF to disable the
messages.

First, let's create a new zipfile (Test.Zip) by using the following command:
  MTZIP CREATE,ZIPFILE,C:\Test.ZIP
Let's add some files to the buffer:
  MTZIP ADD,BUFFER,C:\Config.sys
  MTZIP ADD,BUFFER,C:\Command.com
  MTZIP ADD,BUFFER,C:\AutoExec.bat
  MTZIP ADD,BUFFER,C:\Windows\Himem.sys

Well as you can see the buffer is processed as a "normal" list in VDS. With the
ADD-command you may also use wildcard, so MTZIP ADD,BUFFER,C:\*.sys will add all
files in the C:\ directory with the extension SYS. The easiest way is to create
a real VDS-List, to control the buffer and before processing you simple add all
items from the real VDS-List to the buffer.

The four files above are in the buffer. Let's add the files to the (new) zipfile:
  MTZIP PROCESS,ADD

The DLL will now create the file C:\Test.Zip. To check if everything went right
use the @MTZIP(SUCCESS) to retrieve the number of files that have been added.
It should be 4! Else, check the errorcode with @MTZIP(ERRORCODE) which will return
0 if no error is found.

The second step is to delete two files from the created Test.Zip. First load the file:
  MTZIP LOAD,ZIPFILE,C:\Test.Zip
Add the files to be deleted to the buffer and delete them!
  MTZIP ADD,BUFFER,AutoExec.bat
  MTZIP ADD,BUFFER,Command.com
  MTZIP PROCESS,DELETE
And again @MTZIP(SUCCESS) should be equal to 2.

The final thing that is explained is the examination of the zipfile and how to extract
files. Again with the Test.Zip example file.
  MTZIP LOAD,ZIPFILE,C:\Test.Zip
With @MTZIP(COUNT,ZIPFILE) contains the number of files in the file. The first file is
item 0. The compression ratio of this file is @MTZIP(ZIPFILE,0,RATIO) and the name of
the file is @MTZIP(ZIPFILE,0). Because you now the number of files in the zipfile, you
can easily put them in a real VDS-List with a repeat-until construction. If you want to
extract the third item, add it to the buffer and process it:
MTZIP ADD,BUFFER,@MTZIP(ZIPFILE,1)
MTZIP PROCESS,EXTRACT

At the moment you cannot set the extraction-directory! It will always be extracted to
the current directory, so use DIRECTORY CHANGE,<PATH> to set the extraction directory!
With this information you can get enough out of the current beta-version (I Hope). If
you run against things, don't hesitate to e-mail me.


Futures
-------
The ZIPDLL.DLL and the UNZDLL.DLL are two very powerfull DLL's. Version 1.0 will
get the most out of the DLL's. You will get...

- complete control over the ZIPFILE- and BUFFER-list, so that they can be easily
  used to search for files.
- configurable compression level
- passwords en encryption
- add/extract directory paths in zipfile
- include subfolders when adding 
- disk spanning with options
- test zipfiles
- events to keep track of the progress of (un)zipping on i.e. a progress-bar

That will be it for version 1.0 giving you total control of ZIP. The future version
(2.0?) will allow the creation of SFX-files and complete setup-capabilities like in
VSetup, but with many more options!

Have fun,

Mark Toten